Créer une tâche vidéo

La génération vidéo est une tâche asynchrone : une création réussie signifie seulement que la tâche a été acceptée ; enregistrez l'id de la réponse, puis interrogez la tâche pour lire sa progression et son résultat. Une requête de création correspond à une tâche ; les consultations et l'actualisation de la page ne créent pas de doublon ni ne facturent deux fois.

Pour les conventions communes (adresse de base, authentification, structure de réponse, limitation de débit, idempotence), voir Authentification et conventions de base.

Aperçu des interfaces

Les deux syntaxes ont des corps de requête, des corps de réponse et des ID de tâche identiques ; choisissez l'une ou l'autre. Un même ID de tâche peut être consulté via les deux ensembles de chemins.

Les anciens clients peuvent continuer à utiliser /v1/video/generations ; la plateforme le traite au niveau de la couche d'entrée via le plugin de tâches vidéo de /v1/videos, sans modification de champ ni de chemin.

Préparer les variables

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_API_ORIGIN="https://locopalai.com"
export LOCOPAL_VIDEO_MODEL_ID="从 /v1/models 返回的视频模型 ID"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/reference.png"
export LOCOPAL_VIDEO_URL="https://你的对象存储域名/reference.mp4"
export LOCOPAL_AUDIO_URL="https://你的对象存储域名/reference.mp3"
export LOCOPAL_TASK_ID="创建视频后响应中的 id"

Créer une tâche vidéo

Méthode d'authentification

Authorization: Bearer <API_KEY>, avec la clé API de plateforme créée dans la page « Clés API » de la console.

Corps de requête · application/json

prompt et content : fournissez au moins l'une des deux entrées textuelles. Si seul content est soumis, la plateforme utilise le text du premier élément type: "text" comme invite. En l'absence de model, HTTP 400 est renvoyé ; ne transmettez pas au modèle des paramètres dont la page de détails ne déclare pas la prise en charge.

Éléments de content

Les ressources publiques doivent utiliser une URL HTTPS directement téléchargeable, sans dépendre de Cookie, de Referer ni d'une page de connexion ; les images peuvent également utiliser data:image/...;base64,... selon le support du modèle. Les ressources dont le statut est Active dans la bibliothèque de ressources s'utilisent via asset://<asset_id> ; les ressources de portrait ne peuvent être soumises qu'à des modèles prenant en charge la bibliothèque de ressources de portrait.

Dans le tableau content, image_url, video_url et audio_url sont transmis à l'amont avec leur type d'origine ; les paramètres racine tels que duration, ratio, resolution, seed, watermark et generate_audio sont également soumis avec la tâche et n'ont pas besoin d'être encapsulés dans metadata.

Si vous n'avez besoin que d'une image de référence ordinaire, vous pouvez aussi utiliser la forme abrégée image_url au niveau racine :

{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "prompt": "镜头缓慢推进",
  "image_url": "https://your-object-storage.example/reference.png",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

La plateforme convertit le image_url racine en un seul élément de contenu d'image de référence. Si vous avez besoin de plusieurs images, de frames de début et de fin, ou de vidéos ou audios de référence, utilisez le tableau content.

Exemple de requête

Génération texte-vers-vidéo

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    { "type": "text", "text": "雨后的城市街道，镜头从水面倒影缓慢抬升，电影感" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}
JSON

Génération vidéo à partir d'une seule image

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "人物自然转身，衣摆随风摆动，镜头轻微环绕" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/reference.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

Frames de début et de fin

La première et la dernière frame doivent être marquées respectivement first_frame et last_frame, avec deux images différentes.

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "镜头从室内平滑移动到窗外城市夜景" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://你的对象存储域名/first.png" }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": { "url": "https://你的对象存储域名/last.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

Images multiples et vidéos de référence

Ce que le métier appelle souvent « vidéo profonde » n'a pas de champ deep_video dédié dans l'interface publique ; elle est soumise comme vidéo de référence : type vaut video_url et role vaut reference_video. Chaque image de référence occupe son propre élément content ; ne placez pas plusieurs URL dans un seul image_url.url.

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物为主体，沿用图片2的服装，参考视频的动作节奏和运镜，保持人物身份与产品外观一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "$LOCOPAL_IMAGE_URL" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://你的素材ID" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/scene.png" }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": { "url": "$LOCOPAL_VIDEO_URL" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 7,
  "generate_audio": false,
  "watermark": false
}
JSON

L'ordre du tableau est l'ordre des ressources. Il est recommandé d'indiquer explicitement dans l'invite « image 1, image 2, image 3, vidéo de référence », sans compter sur le serveur pour deviner l'ordre à partir des noms de fichiers. Le nombre d'images de référence, la vidéo de référence, l'audio de référence, la résolution de sortie et la durée dépendent des capacités du modèle ; voir Description des images multiples et des vidéos de référence.

Images multiples, audio de référence et graine fixe

seed permet de fixer le résultat d'échantillonnage ; reference_audio sert de référence de son ou de rythme ; duration, generate_audio, ratio, resolution, watermark sont tous des paramètres racine. L'exemple ci-dessous correspond aux paramètres vidéo 9:16 couramment utilisés par les clients :

{
  "model": "doubao-seedance-2.0-D",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物和服装为主体，参考图片2的另一名角色，参考音频的情绪和节奏生成电影感画面，保持角色身份一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917114312-cyele" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917111324-mquys" }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": { "url": "https://your-object-storage.example/reference.mp3" }
    }
  ],
  "duration": 9,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

Après une création réussie, l'id / task_id de la réponse se consulte toujours selon le flux des tâches asynchrones ; l'audio de référence doit être une adresse HTTPS accessible par la plateforme, et une ressource asset:// doit d'abord être à l'état Active.

Paramètres de réponse

Corps de réponse

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

La réponse de création n'est pas un ensemble de champs fixe. Le client doit se fier au fait que id / task_id ne soit pas vide, et ne pas considérer la présence de object ou progress comme une condition nécessaire à l'acceptation.

Après avoir reçu HTTP 200 et un ID de tâche, même si l'attente locale expire, interrogez uniquement la tâche d'origine ; ne la recréez pas automatiquement.

Réponse d'erreur

Lorsque la validation des paramètres échoue, l'interface renvoie HTTP 400, avec code valant invalid_request et message indiquant directement le contenu manquant ou mal saisi :

{
  "code": "invalid_request",
  "message": "缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述",
  "data": null
}

Lorsque le solde ou le quota de la clé API actuelle ne suffit pas à couvrir le coût estimé, l'interface renvoie HTTP 403 sans créer de tâche ni engendrer de frais :

{
  "code": "insufficient_user_quota",
  "message": "余额不足：本次预计需要 ＄11.500000，当前可用 ＄0.002000，请充值或调整参数后重试",
  "data": null
}

Concurrence et rythme de soumission

Les tâches de génération s'exécutent en concurrence en arrière-plan ; la soumission et le téléchargement des résultats consomment la bande passante sortante de la plateforme. La plateforme impose donc une limite au nombre de tâches simultanément en cours de traitement : au maximum 2000 par compte à la fois. Une soumission après avoir atteint la limite renvoie :

{
  "code": "task_concurrency_exceeded",
  "message": "当前账号有 2000 个生成任务正在处理中，已达到并发上限 2000，请等待任务完成后再提交",
  "data": null
}

Il est recommandé d'organiser les tâches en lot ainsi :

• soumettez d'abord un lot, attendez que les tâches atteignent un état final completed / failed, puis soumettez le lot suivant ; ne réessayez pas la même requête en boucle continue ;
• plus une soumission contient d'images de référence ou plus la résolution est élevée, plus elle occupe longtemps la bande passante sortante ; réduisez d'autant le nombre de tâches soumises simultanément ;
• pour produire plusieurs vidéos en parallèle, suivez la progression par ID de tâche et continuez après la fin du lot précédent, afin d'éviter les doubles facturations dues aux soumissions en double.

Facturation et validation des paramètres

• les tâches vidéo sont réglées selon l'usage réel à leur achèvement : une création réussie signifie seulement que la tâche a été acceptée ; la phase de soumission n'effectue aucune déduction anticipée et ne génère aucun enregistrement de facture ; une fois la tâche terminée, la facture ne contient qu'une seule ligne de débit réel.
• lors de la soumission, la plateforme vérifie si le solde du compte (ou le quota de la clé API actuelle) couvre le quota estimé. En cas d'insuffisance, elle renvoie HTTP 403 et insufficient_user_quota, avec un message indiquant « nécessaire pour cette fois …, disponible actuellement … » ; rechargez ou ajustez les paramètres puis soumettez à nouveau. Aucune tâche n'est créée et aucun frais n'est engendré dans ce cas.
• le corps de la requête est validé avant la soumission ; en cas de contenu manquant, un message lisible est renvoyé directement, sans avoir à compter sur une erreur amont :