Démarrage rapide

LocoPal propose actuellement deux parcours courants : créer directement dans LocoPal Creation, ou utiliser l'API de LocoPal Ai pour intégrer ses propres services.

Les deux modes partagent le même compte LocoPal, le même catalogue de modèles et le même système de facturation. Cette page se concentre sur LocoPal Ai et LocoPal Creation.

Étape 1 : S'inscrire ou se connecter à LocoPal Ai

1. Ouvrez LocoPal Ai. Si vous avez déjà un compte, connectez-vous directement ; sinon, accédez à la page d'inscription.
2. La page d'inscription actuelle exige de définir un nom d'utilisateur et un mot de passe, et d'effectuer une vérification par SMS. Le mode de vérification peut évoluer selon la politique de sécurité ; les indications réelles de la page d'inscription font foi.
3. Après connexion, vérifiez le solde du compte, le quota du forfait ou les points disponibles. Avant d'utiliser Creation ou l'API, confirmez l'état de disponibilité du compte.

Étape 2 : Utiliser directement LocoPal Creation

Si votre objectif est de générer du contenu directement, il est recommandé de commencer par utiliser Creation : aucun code à écrire, aucune API Key à créer.

1. Ouvrez LocoPal Creation.
2. Creation ne dispose pas de compte indépendant. Si vous n'êtes pas connecté, la page redirige vers la connexion LocoPal ; une fois l'autorisation accordée, elle revient automatiquement à Creation sans redemander le mot de passe.
3. Sur la page d'accueil, choisissez le mode intelligent, le dessin IA, la vidéo IA ou l'audio IA et saisissez votre besoin ; une fois dans l'atelier, vous pouvez également utiliser les entrées mini-séries, œuvres, ressources, prompts, lexique et place de marché des œuvres.
4. Lorsque vous devez conserver la cohérence d'un personnage, d'un produit ou d'un style, téléchargez une image de référence ou sélectionnez une ressource existante avant de soumettre.
5. Après la soumission, consultez l'état de la tâche sur la page actuelle, prévisualisez le résultat et téléchargez-le ou continuez à le référencer. Actualiser la page ne recrée pas la tâche ; ne soumettez pas plusieurs fois une tâche en cours d'exécution.

La portée des modèles disponibles dans Creation est identique au catalogue de modèles actuel de LocoPal Ai, et la consommation des appels est uniformément imputée au compte LocoPal actuel. Si un modèle n'est pas disponible, vérifiez d'abord dans la place de marché des modèles de LocoPal Ai si ce modèle est déjà activé dans l'un des groupes disponibles.

Étape 3 : Intégrer l'API et créer une API Key

Accédez à « Clés API » dans la console LocoPal Ai et cliquez sur créer. Il est recommandé de créer des clés distinctes pour le « service de production / l'environnement de test / l'application client », afin de consulter les journaux par application, de limiter les quotas et de désactiver rapidement une clé compromise.

Vérifiez en priorité lors de la création :

• Le nom de la clé sert à distinguer les appelants ;
• Le groupe d'appel détermine quels modèles cette clé peut voir et appeler ;
• Le quota et la période de validité servent à limiter les consommations anormales ;
• Une seule clé permet d'appeler les interfaces de modèles, d'images, de vidéos, d'audio et de ressources ; il n'est pas nécessaire de créer des clés différentes pour chaque interface.

L'API Key ne doit être conservée que dans les variables d'environnement du serveur ou dans un service de gestion des secrets ; ne l'inscrivez pas dans le code source d'une page web, dans un paquet d'application mobile, dans un dépôt public, dans des journaux ou dans des captures d'écran.

Étape 4 : Préparer l'adresse de base

Adresse de base par défaut :

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"

La console de la plateforme peut également afficher des adresses d'accès destinées aux modèles étrangers ou à des environnements réseau spécifiques, par exemple :

https://us-api.locopalai.com

Lors de l'intégration réelle, utilisez l'adresse actuellement affichée par la console. LOCOPAL_BASE_URL doit s'arrêter au domaine, sans ajouter /v1 de façon répétée ; le chemin de l'interface contient déjà /v1 ou /api/v1.

Étape 5 : Interroger les modèles disponibles pour la clé actuelle

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

• Le model de la requête doit utiliser data[].id, et non le nom affiché sur la page ;
• Un retour "data": [] indique qu'aucun modèle n'est disponible dans le groupe d'appel de la clé actuelle ; vérifiez d'abord la configuration du groupe ou contactez le support de la plateforme ;
• Le catalogue de modèles évolue avec les autorisations du compte, l'adresse d'accès et la disponibilité de la plateforme ; il est recommandé de le réinterroger au démarrage du service, lors du changement de modèle par l'utilisateur ou à la réception d'un « modèle indisponible » ;
• Une même clé peut voir des ensembles de modèles différents sur locopalai.com et sur us-api.locopalai.com ; l'adresse utilisée détermine le résultat de /v1/models qui fait foi ;
• La possibilité d'appeler un modèle dépend du résultat /v1/models pour la clé actuelle ; ne codez pas les noms de modèles en dur.

Utiliser supported_endpoint_types pour déterminer quel exemple utiliser

data[].supported_endpoint_types indique directement à quel type d'interface ce modèle correspond ; choisissez l'exemple en conséquence :

Le supported_endpoint_types d'un modèle peut contenir plusieurs éléments à la fois, ce qui signifie qu'il peut être appelé via plusieurs interfaces.

Étape 6 : Premier appel texte

curl -X POST "$LOCOPAL_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的文本模型 ID",
    "messages": [{ "role": "user", "content": "用三句话介绍这个产品" }],
    "stream": false
  }'

En cas de succès, lisez le texte depuis choices[0].message.content et conservez le champ usage de la réponse pour le rapprochement comptable. Un modèle de raisonnement peut consommer la totalité de max_tokens dans completion_tokens_details.reasoning_tokens ; dans ce cas, message.content est vide et finish_reason vaut length ; augmentez la limite de sortie ou utilisez un modèle non raisonnant avant de réessayer. Avec stream: true, lisez la réponse par segments SSE jusqu'à [DONE].

Étape 7 : Premier appel image

curl -X POST "$LOCOPAL_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的图片模型 ID",
    "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

Le résultat est généralement renvoyé dans data[] sous forme de url ou de b64_json. L'URL renvoyée peut être une adresse temporaire et doit être copiée rapidement ; size, quality et response_format dépendent du modèle d'image actuel ; certains modèles GPT Image refusent response_format et renvoient unknown_parameter, auquel cas retirez ce champ. Lorsqu'une image sert de référence à une vidéo ultérieure, ajoutez-la d'abord à la bibliothèque de ressources via l'interface correspondante et attendez que son statut soit Active, puis référencez-la avec asset://<asset_id>.

Étape 8 : Premier appel vidéo

La vidéo est une tâche asynchrone : l'interface de création renvoie un ID de tâche, et l'interface de consultation renvoie la progression et le résultat.

POST /v1/video/generations et POST /v1/videos utilisent le même corps de requête et le même format de réponse ; choisissez l'un ou l'autre. L'ancien chemin d'appel est automatiquement traité par la plateforme via le plugin de tâche vidéo.

curl -X POST "$LOCOPAL_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "清晨的湖边，镜头缓慢向前推进" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
JSON

{
  "created_at": 1789567067,
  "id": "task-public-id",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task-public-id"
}

La réponse de création ne doit s'appuyer que sur id / task_id, status, model et created_at ; des champs comme object et progress peuvent n'apparaître qu'après la première consultation et ne doivent pas être considérés comme des conditions nécessaires au succès de la création.

Conservez l'id de la réponse de création, puis interrogez la même tâche :

export LOCOPAL_TASK_ID="创建响应里的 id"

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Une fois la tâche réussie, lisez metadata.url pour télécharger ou lire le résultat. La plateforme renvoie en priorité l'URL vidéo d'origine fournie en amont ; si l'amont ne renvoie pas d'adresse lisible, elle se rabat sur l'adresse d'artefact de la plateforme. Les paramètres vidéo renvoyés par l'amont peuvent inclure :

{
  "metadata": {
    "url": "https://上游原始视频地址",
    "upstream_created": true
  },
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800
}

Parmi ces champs, duration_secs correspond à la durée ; expires_at n'apparaît que si l'amont concerné le renvoie ; les autres paramètres vidéo n'apparaissent de même que lorsque le modèle et l'amont les renvoient réellement. Une fois l'ID de tâche obtenu, même si l'attente locale expire, vous ne devez que continuer à interroger la tâche d'origine et non la recréer, sous peine de générer des tâches en double et des frais supplémentaires.

Si le status du résultat de consultation est failed, lisez error.code et error.message de la même réponse. L'échec terminal d'une tâche vidéo utilise généralement video_generation_failed ; error.message est la raison lisible après nettoyage par la plateforme, et il ne faut pas tenter d'en réanalyser le JSON :

{
  "id": "task-public-id",
  "status": "failed",
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  }
}

Étape 9 : Premier appel de synthèse vocale

La plateforme fournit une interface POST /v1/audio/speech compatible OpenAI. Sa disponibilité dépend du groupe et du catalogue de modèles de l'API Key actuelle ; les timbres, formats et paramètres de vitesse pris en charge dépendent du modèle réel.

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Le corps d'une réponse réussie est un flux audio binaire, et non du JSON ; l'exemple utilise --output pour l'enregistrer sous speech.mp3. L'état asynchrone et les artefacts des autres tâches audio peuvent être consultés dans les « Journaux de tâches ».

Étape 10 : Premier appel de ressources

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "我的角色素材",
  "description": "视频参考图",
  "type": "virtual"
}
JSON

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "我的角色素材",
      "type": "virtual",
      "description": "视频参考图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

Conservez data.group.id, soumettez l'image et interrogez le statut par polling :

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-id","title":"角色正面图","image_url":"https://你的对象存储域名/person.png"}'

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

image_url utilise une adresse http(s) directement téléchargeable depuis l'internet public ; data_url peut également être soumis selon les limites de l'interface. Une fois que data.asset.status passe à Active, la ressource peut être référencée dans une requête vidéo via asset://<asset_id>. Les paramètres complets et les descriptions d'erreurs sont disponibles dans l'interface de la bibliothèque de ressources.

Étape 11 : Ressources de personnes réelles (facultatif)

Les ressources de personnes réelles doivent être collectées et autorisées par la personne elle-même en scannant un QR code avec son téléphone ; un simple téléchargement d'image ne peut pas les remplacer. Le parcours dans la console est « Gestion de la bibliothèque de ressources → Nouveau groupe → Ressources de personnes réelles → Générer un QR code → Scan par la personne concernée → Scan terminé, démarrer la synchronisation » ; le parcours via l'interface est décrit dans Créer une session de scan pour personne réelle.

Étapes suivantes