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

Cette page répond aux questions d'intégration programmatique de « plusieurs images de référence + une vidéo de référence », notamment les limites de capacités, les règles d'ordre, la vidéo de profondeur, l'audio, la reprise des tâches et la facturation. Le tableau complet des champs du corps de requête et les exemples copiables se trouvent dans Interface de génération vidéo, et l'import des ressources dans Interfaces de la bibliothèque de ressources.

Conclusions à retenir

• Plusieurs images et une vidéo de référence utilisent le même tableau content : chaque image occupe un élément image_url, la vidéo occupe un élément video_url.
• « Vidéo de profondeur » n'a pas de champ deep_video distinct ; soumettez-la comme une vidéo de référence ordinaire, avec role défini sur reference_video.
• L'ordre du tableau est l'ordre des ressources. Il est recommandé d'indiquer explicitement dans le prompt « image 1, image 2, image 3, vidéo de référence », sans compter sur le serveur pour deviner l'ordre d'après les noms de fichier.
• generate_audio: false signifie désactiver la sortie audio du résultat généré ; cela ne signifie pas conserver la piste audio d'origine de la vidéo de référence d'entrée, ni copier l'audio d'entrée dans la vidéo finale.
• Les limites précises de nombre d'images, de nombre de vidéos, de taille de fichier, d'encodage et de concurrence dépendent du catalogue de modèles et des réponses réelles de l'interface ; la plateforme ne garantit pas un ensemble de limites uniformes pour toutes les variantes de Seedance.
• Si vous devez absolument conserver les mouvements, les positions de caméra et les coupes du plan d'origine, la vidéo de référence ne peut servir que de référence au modèle. La requête publique actuelle ne dispose d'aucun paramètre générique pour « forcer une coupe à la Nième seconde » ; la synchronisation précise ne peut pas être garantie uniquement par les champs de l'interface.

1. Vérifier les capacités du modèle actuel

Lisez d'abord le catalogue de modèles visible pour la clé actuelle :

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Le catalogue confirme seulement « si le modèle est visible et pour quelles interfaces il est disponible » ; c'est data[].id qui constitue le model à renseigner dans la requête. Les limites concrètes telles que le nombre d'images de référence, la vidéo de référence, l'audio de référence, le ratio de sortie, la durée et la résolution dépendent de la page de détail du modèle et des erreurs de paramètres renvoyées par l'interface ; la plateforme ne devine pas à la place du modèle les limites non listées dans le catalogue.

2. Import et référencement des ressources de référence

Les illustrations de personnages fictifs, les vues multiples d'un personnage et les images de scène sans personne ne sont pas des ressources soumises à autorisation de portrait ; importez-les comme des ressources virtuelles ordinaires :

POST /api/v1/materials/groups
POST /api/v1/materials/assets
GET  /api/v1/materials/assets/{asset_id}

Une fois le statut de la ressource passé à Active, l'URL de l'image dans la requête vidéo peut être remplacée par :

asset://asset-20260911035115-etexu

Lorsque les images sont importées une par une, chacune obtient un asset_id distinct. Les images de personnage et les images de scène peuvent être placées dans le même groupe virtuel ou dans des groupes séparés ; lors de la soumission de la vidéo, référencez-les via des éléments content différents. L'import, l'interrogation répétée et les réponses d'erreur sont décrits dans Interfaces de la bibliothèque de ressources.

En cas de soumission réussie, status vaut généralement Processing, puis passe à Active une fois le traitement terminé ; en cas d'échec, status vaut Failed et error_message en donne la cause. La validation est asynchrone ; la plateforme ne garantit pas une durée uniforme pour toutes les images, le programme doit interroger le même asset_id et ne pas soumettre à nouveau pendant Processing.

3. Plusieurs images + une vidéo de référence

La requête suivante exprime « 1 image de personnage + 2 images de scène + 1 vidéo de référence ». Les indices du tableau commencent à 1 :

1. content[1] est l'image 1, l'image du personnage ;
2. content[2] est l'image 2, la scène 1 ;
3. content[3] est l'image 3, la scène 2 ;
4. content[4] est la vidéo de référence.

content[0] est le prompt textuel et n'entre pas dans la numérotation des images.

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    {
      "type": "text",
      "text": "图片1是人物身份参考，图片2和图片3是场景参考。参考视频用于动作、机位和镜头节奏参考；保持人物身份和场景关系一致。"
    },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://人物素材ID" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID1" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID2" } },
    { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://你的对象存储域名/reference-depth.mp4" } }
  ],
  "duration": 7,
  "resolution": "720p",
  "ratio": "9:16",
  "generate_audio": false,
  "watermark": false
}

En cas de création réussie, l'ID de tâche est renvoyé ; interrogez ensuite uniquement cette tâche :

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

Si la réponse indique explicitement que le modèle actuel ne prend pas en charge la bibliothèque de ressources, utilisez plutôt une adresse d'image HTTPS publique prise en charge par ce modèle ou changez de modèle ; ne contournez pas la validation des ressources. Les exemples complets de réponse de création et d'interrogation sont décrits dans Interface de génération vidéo.

4. Limites des vidéos de référence, du son et de la vidéo de profondeur

Une vidéo de référence n'est pas une piste de contrôle précise

Dans la structure de l'interface publique, la vidéo de profondeur en niveaux de gris reste une reference_video ordinaire. Sauf si le détail du modèle actuel déclare séparément une capacité de contrôle de profondeur, la plateforme n'interprète pas les valeurs de gris comme une contrainte de profondeur et ne garantit pas une reproduction stricte de la profondeur, de la trajectoire des mouvements ou des coupes de la vidéo d'origine.

Une vidéo de référence peut aider le modèle à comprendre les mouvements, la position de caméra, la composition et le rythme, mais la vidéo finale est toujours régénérée par le modèle. La requête publique actuelle ne comporte ni piste de timecode générique ni champ de coupe forcée ; s'il faut s'approcher d'une coupe à un instant donné, vous ne pouvez l'indiquer que dans le prompt et vérifier la vidéo finale après génération ; si une précision à l'image près est indispensable, cela doit être réalisé lors du montage ou de la composition externe.

Piste audio d'entrée et generate_audio

Lorsque la vidéo de référence comporte une piste audio d'origine, la lecture ou non de cette piste par le modèle dépend de l'implémentation de la vidéo de référence du modèle actuel. La signification certaine de generate_audio: false est la désactivation de la sortie audio du résultat généré ; elle ne garantit ni la copie de la piste audio de la vidéo d'entrée, ni l'utilisation de la piste d'entrée comme audio de référence indépendant.

• Si l'objectif est de « générer une vidéo sans son », vous pouvez passer generate_audio: false ;
• Si l'objectif est de « conserver le son d'origine », ne vous fiez pas uniquement à ce champ : après avoir téléchargé la vidéo finale, traitez-la avec votre propre processus de composition audio-vidéo, ou choisissez une configuration dont le détail du modèle déclare explicitement la prise en charge de l'audio de référence et de l'audio de sortie ;
• Si le détail du modèle ne déclare pas la prise en charge de l'audio de référence, ne soumettez pas de reference_audio supplémentaire.

5. Limites actuellement non garanties de manière uniforme

À propos de « le groupe actuel prend-il en charge cet ensemble de requêtes »

Le groupe d'appel et le groupe de ressources sont deux concepts différents ; il ne faut pas juger de la prise en charge des images multiples ou des vidéos de référence uniquement d'après le nom du groupe dans la console. L'ordre réel de vérification est le suivant :

1. le modèle choisi existe dans /v1/models ;
2. le détail du modèle autorise explicitement les images de référence et la vidéo de référence ;
3. le statut de la ressource référencée est Active ;
4. l'interface de création renvoie queued, ce qui indique que la requête a été acceptée ;
5. si le résultat final est failed, lisez error.code et error.message pour déterminer s'il s'agit d'un problème de combinaison ou de ressource.

La plateforme ne basculera pas silencieusement un modèle qui ne prend pas en charge les vidéos de référence vers un autre modèle, afin d'éviter des coûts et des résultats imprévisibles.

6. Reprise des tâches, limitation de débit, idempotence et facturation

Interrogation et reprise

Après que l'interface de création a renvoyé id, vous devez l'enregistrer immédiatement ; si le réseau est interrompu mais que l'ID de tâche a déjà été obtenu, interrogez uniquement la tâche d'origine. L'interface publique actuelle ne propose pas de moyen générique de retrouver une tâche à partir de « prompt + ressources + paramètres » ; si la connexion est interrompue avant le retour de la réponse de création et qu'aucun ID de tâche n'a été obtenu, la plateforme ne peut pas garantir la récupération de la tâche d'origine à partir du seul corps de requête. L'appelant doit donc enregistrer sa requête métier dans sa propre base de données et stocker immédiatement l'ID de tâche dès réception de la réponse d'acceptation.

Interrogation répétée, limitation de débit et conservation

La plateforme ne publie pas uniformément le nombre de requêtes simultanées et la fréquence d'interrogation par clé API pour tous les groupes d'appel ; le client doit respecter la réponse 429 et utiliser une interrogation avec repli exponentiel, de préférence toutes les 5 à 15 secondes. Après la génération de la vidéo finale, téléchargez-la ou transférez-la dès que possible ; ne considérez pas l'URL renvoyée comme une adresse permanente. Si la tâche est encore interrogeable mais que metadata.url a expiré, interrogez d'abord à nouveau la tâche d'origine ; si le lien ne peut être restauré, l'interface publique ne garantit pas de pouvoir régénérer la même adresse.

Idempotence et numéro de requête client

L'interface vidéo publique actuelle ne promet aucun champ d'idempotence officiel contrôlable par l'utilisateur, et ne garantit pas qu'un numéro de requête personnalisé permette une déduplication selon le corps de requête. L'appelant peut utiliser son propre numéro de requête métier pour enregistrer les associations, mais ne doit pas le considérer comme une clé d'idempotence que la plateforme reconnaîtra nécessairement ; côté plateforme, seule la réception d'un ID de tâche constitue une base de reprise fiable.

Changement de clé API

L'appartenance des tâches et des ressources est déterminée par le compte de la plateforme ; sous le même compte, après un changement de clé, vous pouvez continuer à interroger la tâche d'origine en réessayant l'interrogation avec la clé utilisée lors de la création de la tâche. Si la nouvelle clé n'appartient pas au même compte, l'interrogation renvoie 401 ou 404 ; dans ce cas, ne recréez pas la tâche pour contourner l'échec d'interrogation.

Facturation, échecs et remboursements

La facturation de l'import, de la validation, du téléchargement des vidéos de référence et de la génération vidéo dépend du modèle actuel et de la configuration tarifaire de la plateforme. La tâche vidéo est réglée à l'achèvement selon l'usage réel ; une création réussie n'entraîne pas de pré-autorisation, et une seule ligne de frais réels apparaît dans la facture après l'achèvement ; avant la soumission, le solde est vérifié pour couvrir l'estimation, et s'il est insuffisant, un message lisible est renvoyé directement sans créer de tâche. Les données de coût n'apparaissent dans la réponse d'interrogation qu'après le règlement :

• La réponse de création indique seulement que la tâche a été acceptée ; il n'y a alors aucune donnée de règlement, donc aucun champ de frais n'est renvoyé ; ne jugez pas le coût de cette exécution d'après la réponse de création ;
• La réponse d'interrogation renvoie usage après le règlement de la tâche : usage.total_tokens est le nombre de tokens vidéo facturés cette fois (l'amont ne rapporte qu'un nombre de tokens, enregistré selon la base de facturation de la plateforme dans usage.prompt_tokens, usage.completion_tokens valant 0), usage.quota correspond aux crédits consommés, usage.amount est le montant en yuans converti à partir de ces mêmes crédits (usage.currency vaut toujours CNY) ;
• Un échec de validation des paramètres (HTTP 400 / 403) signifie que la requête n'a pas été acceptée et n'entraîne pas de frais de génération ;
• Une fois l'ID de tâche renvoyé, la facturation éventuelle et le remboursement en cas d'échec sont traités selon les règles de facturation du modèle et de la plateforme ;
• Les règles de facturation et de remboursement en cas d'échec de validation, d'échec de génération ou d'annulation de tâche ne peuvent pas être déduites du seul statut de la tâche ;
• Pour vérifier les frais, conservez l'ID de tâche, l'ID de modèle, la date de création et le compte associé à la clé API, puis vérifiez avec usage.quota / usage.amount de la réponse d'interrogation dans la facturation de la console, ou contactez le support de la plateforme.

7. Réponses d'erreur courantes

{
  "error": {
    "code": "invalid_parameter",
    "message": "当前模型不支持参考视频，或参考素材数量超出限制",
    "type": "invalid_request_error",
    "param": "content"
  }
}