Tutoriel
Tutoriel de l'API seedance-2.5-flash image-to-video : curl et Python Requests
Un exercice pratique d'intégration pour les développeurs : structure de requête, entrées de première/dernière frame, polling asynchrone et diagnostic des erreurs
Sur cette page
Ce que fait réellement un appel image-to-video
Avant d'écrire la première ligne de code, il est utile de comprendre ce que fait l'API de l'autre côté. Un appel à seedance-2.5-flash/image-to-video n'est pas une requête synchrone qui bloque jusqu'au retour du fichier vidéo. Il s'agit d'un workflow asynchrone en deux phases : vous soumettez d'abord une tâche, puis vous interrogez son résultat.
Phase de soumission
Vous envoyez une requête POST avec l'image d'entrée et les paramètres de génération. L'API valide le corps de la requête, met la tâche en file d'attente et renvoie immédiatement une réponse contenant l'identifiant de la tâche et son état initial. Ce processus est rapide — généralement instantané — car aucun pixel n'est encore rendu. Votre rôle est de capturer cet identifiant et de le conserver soigneusement.
Phase de rendu
La génération s'effectue en arrière-plan. Selon la durée du clip et les paramètres, cela peut prendre un temps réel considérable. Pendant cette fenêtre, ne vous attendez pas à ce que l'URL finale de la vidéo soit déjà disponible. Interrogez plutôt l'état de la tâche.
Phase de résultat
La tâche finit par atteindre un état terminal : réussite, avec un artefact vidéo téléchargeable ; ou échec, avec une erreur permettant le diagnostic. Une fois l'état terminal atteint, arrêtez le polling.
Pourquoi cela compte pour votre code
Parce que le modèle est asynchrone, l'erreur d'intégration la plus courante est architecturale, et non syntaxique : supposer que la première réponse contient déjà la vidéo, dormir à intervalle fixe au lieu d'interroger le champ d'état, et ne pas distinguer un état transitoire processing d'un échec définitif. Tout ce tutoriel s'articule autour d'une boucle propre « soumettre → interroger → sortir », gardez donc ces trois phases à l'esprit pendant votre lecture.
Prérequis et structure de la requête
Ce qu'il faut préparer avant le premier appel
- Identifiants API. Votre clé API HiAPI, envoyée avec chaque requête. Conservez-la dans une variable d'environnement (
HIAPI_API_KEY) plutôt que dans la gestion de code source — les exemples ci-dessous la lisent ainsi. - Identifiant du modèle. Dans ce tutoriel, la chaîne est fixe :
seedance-2.5-flash/image-to-video. Traitez-la comme une constante opaque ; ne la construisez pas par concaténation de parties. - Image source. Une URL publique ou une référence d'image en ligne prise en charge. Le modèle nécessite au minimum une image de première frame.
- Client HTTP.
curlpour les tests de fumée, etrequestspour tout ce que vous comptez conserver.
Les champs logiques du corps de la requête
Quel que soit le langage, le corps d'une requête image-to-video se compose de plusieurs groupes conceptuels. Les connaître séparément rend le JSON plus facile à comprendre :
Modèle et entrées
- L'identifiant du modèle.
- Un objet d'entrée contenant l'image de première frame et, en option, l'image de dernière frame. Le chapitre 4 explique comment elles interagissent.
Paramètres de sortie
- Les options liées à la résolution et à la durée.
- L'option d'audio natif, qui détermine si le clip généré comporte une piste sonore associée. Le chapitre 5 explique quand l'activer.
Ce qui est renvoyé
Une soumission réussie renvoie un objet tâche. Les champs dont vous avez réellement besoin sont l'identifiant de la tâche et l'état actuel. Tout le reste est des métadonnées que vous pouvez journaliser ou ignorer. Ne parsez pas toute la réponse dans un modèle typé dès le premier jour — journalisez, inspectez, puis affinez.
Une vérification rapide avant de continuer : si votre corps de requête contient un champ dont vous ne pouvez pas expliquer le nom en une phrase, supprimez-le et repartez du minimum. La page du modèle seedance-2.5-flash/image-to-video est la référence pour les noms de champs exactement acceptés.
Soumettre une tâche avec curl
Commencez par la requête minimale susceptible de fonctionner, puis ajoutez les champs un par un. Voici une soumission minimale avec curl :
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
Commentaire champ par champ
Authorization— votre clé API, en tant que bearer token. Si cette partie est erronée, vous recevrez une erreur d'authentification avant toute validation ; vérifiez-la donc en premier lors du débogage.Content-Type: application/json— obligatoire ; l'omettre produit des erreurs en aval déroutantes.model— l'identifiant fixe du modèle. Une faute de frappe ici renvoie une 4xx, et non un repli silencieux.input.first_frame_image— l'image d'ouverture du clip. Utilisez une URL réellement accessible depuis votre réseau ; une URL privée ou expirée échouera lors de la récupération, et non à la soumission.
Lire la réponse
La réponse est un JSON contenant l'identifiant de la tâche et l'état. Enregistrez immédiatement l'identifiant — c'est ce que vous interrogerez au chapitre 7. Une méthode rapide pour l'extraire dans le shell :
# après le curl ci-dessus, passez par jq
# {"job_id": "...", "status": "queued"}
Ajouter une dernière frame
Pour contrôler aussi l'image finale, ajoutez une seconde image dans le même objet input. Les noms de champs et les formats acceptés sont ceux de la documentation du modèle — ne devinez pas de variantes orthographiques ; l'API rejette les clés inconnues plutôt que de les ignorer.
Une fois la requête minimale fonctionnelle, vous disposez d'un test de fumée à relancer en cas de problème. Conservez-le dans un fichier ; lorsque le service tombe à deux heures du matin, il vaut plus que tout long discours.
Entrées de première et dernière frame
Les images d'entrée sont le facteur déterminant le plus important de la réussite d'une tâche. Elles façonnent le contenu du clip et constituent aussi la source la plus fréquente de rejets de requêtes.
Ce que contrôle la première frame
L'image de première frame définit l'état initial du clip généré : composition, sujet, éclairage et couleurs. Le modèle génère le mouvement et la continuité à partir de ce point de départ, l'image doit donc ressembler à la frame que vous souhaitez réellement voir à l'instant zéro. Une image source floue, recadrée ou fortement compressée ne s'améliorera pas miraculeusement plus tard.
Ce que contrôle la dernière frame
Fournir une image de dernière frame fixe l'état final. C'est utile lorsque le clip doit se terminer sur un plan précis — une frame produit soignée, la révélation d'un logo, une transition raccord dans un montage. Si elle est omise, le modèle choisit lui-même la fin, ce qui convient à l'exploration mais reste imprévisible en production.
Comment les deux interagissent
Lorsque les deux sont fournies, le modèle interpole entre elles. Cela a des conséquences pratiques :
- La continuité prime sur le contraste. Deux frames d'une même scène avec un mouvement modéré produisent un clip plus cohérent que deux images sans rapport. Si les frames diffèrent fortement, attendez-vous à une déformation visible plutôt qu'à une transition plausible.
- Les ratios d'aspect doivent correspondre. Un ratio d'aspect différent entre la première et la dernière frame force le modèle à un recadrage maladroit. Recadrez les deux au même ratio avant de soumettre.
- Les résolutions doivent être comparables. Envoyer une première frame nette et une dernière frame basse résolution donne des signaux contradictoires au modèle.
Liste de vérification avant soumission
Avant d'envoyer, vérifiez : les deux URL d'image sont accessibles publiquement et n'expireront pas en cours de tâche ; les deux sont dans un format pris en charge ; les deux ont le même ratio d'aspect ; aucune n'est une capture d'écran contenant des éléments d'interface que vous ne souhaitez pas voir rendus. Une requête HEAD rapide sur chaque URL capte la plupart de ces problèmes à moindre coût qu'une tâche de génération échouée.
Si vous rencontrez malgré tout un rejet, le message d'erreur pointe généralement vers l'objet d'entrée. Validez d'abord les images en local — dimensions, format et accessibilité — avant de suspecter l'API.
Paramètres de résolution et d'audio natif
Les paramètres de sortie sont l'endroit où les développeurs ont tendance à surconfigurer. La bonne nouvelle est que les valeurs par défaut sont raisonnables ; le risque est de copier des valeurs provenant de la documentation d'un autre modèle.
Résolution
La résolution détermine la taille de la vidéo livrée et, par conséquent, le temps de génération et le volume de sortie. Deux règles empiriques :
- Choisissez pour la destination cible, pas pour le chiffre. Un clip destiné à un fil mobile n'a pas besoin d'être rendu en grand format puis réduit. Choisissez la plus petite résolution qui satisfait la plateforme cible.
- Privilégiez l'un des presets de la documentation. Passer une valeur arbitraire ou non prise en charge est une cause fréquente de rejet de requête. Si vous avez besoin d'une taille précise, recadrez ou redimensionnez après génération plutôt que de vous battre avec le validateur de la requête.
Audio natif
L'option d'audio natif détermine si le clip généré inclut une piste sonore produite avec la vidéo. Demandez-vous si vous en avez besoin :
- Activez-la lorsque le clip est le livrable final regardé avec le son — contenu social, courte promotion, scènes de personnages où l'audio d'ambiance renforce la sensation de mouvement.
- Désactivez-la lorsque vous ajouterez votre propre musique ou voix off dans un éditeur, ou lorsque le clip est un actif intermédiaire. Générer de l'audio que vous allez jeter est du travail perdu et alourdit le traitement en aval.
Durée
La durée est couplée à tout le reste : un clip plus long se génère plus lentement et est plus sujet à une dérive de cohérence du sujet. Pour une première intégration, commencez court. Confirmez que le pipeline fonctionne de bout en bout avec un clip bref, puis allongez une fois le pipeline validé.
Gardez l'objet de paramètres compact
Si vous vous surprenez à ajouter des paramètres pour corriger des problèmes de qualité, arrêtez-vous et vérifiez si le problème ne vient pas en fait des images d'entrée. La plupart des sorties décevantes remontent au chapitre 4, et non à l'absence d'un réglage. Configurez de manière intentionnelle, journalisez l'objet de paramètres exact avec chaque identifiant de tâche, et vous pourrez attribuer les variations de qualité à un ajustement précis.
La même requête en Python
La requête curl se transpose directement en Python. L'objectif ici n'est pas un framework — mais un petit client lisible qui soumet la tâche et renvoie l'identifiant, afin que la couche de polling reste séparée.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
Pourquoi cette structure
- Configuration par variables d'environnement. L'URL de base et la clé restent hors du code, de sorte que le même client peut fonctionner sur différents environnements.
timeout=30à la soumission. La soumission est rapide ; une soumission qui bloque indique un problème réseau ou d'authentification que vous voulez détecter tôt plutôt que bloquer indéfiniment un worker.raise_for_status()avant le parsing. Un corps de réponse 4xx est généralement un objet d'erreur JSON, et non une tâche. Lever une exception d'abord garde le chemin nominal propre et laisse l'appelant gérer explicitement l'échec.- Soumission et polling séparés.
submit_jobfait une seule chose. La boucle de polling du chapitre suivant reçoit le dictionnaire renvoyé et se charge de l'attente.
Portage dans un service
Dans un vrai service, enveloppez l'appel pour que les échecs se présentent sous forme d'exceptions typées portant le code de statut et le corps de réponse — vous aurez besoin du corps brut pour déboguer en production. Journalisez le corps de la requête avec l'identifiant de tâche renvoyé ; lorsqu'un collègue demande pourquoi un clip semble bizarre, cette ligne de journal est toute l'enquête.
Les noms de champs sont exactement identiques à l'exemple curl. Si vous savez lire l'un, vous savez lire l'autre — c'est précisément pourquoi commencer par curl vaut cinq minutes.
Interroger le résultat sans marteler l'API
La tâche existe maintenant et possède un identifiant. L'approche naïve — dormir soixante secondes puis espérer — échoue de deux façons : elle perd du temps si la tâche se termine plus tôt, et échoue complètement si la tâche prend plus longtemps.
Interrogez le champ d'état, pas l'horloge
Écrivez une boucle qui interroge l'état actuel de la tâche et branche en conséquence :
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # backoff exponentiel borné
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
Les caractéristiques importantes
- États terminaux explicites. Seuls
succeededetfailedterminent la boucle. Tout autre état est transitoire. Ne traitez pas un état inconnu comme un échec — de nouveaux états intermédiaires apparaissent au fil du temps, et votre boucle doit les tolérer. - Backoff borné. Commencez petit (quelques secondes), augmentez avec un facteur modéré, plafonnez autour de dix à quinze secondes. Cela garde les tâches courtes réactives sans marteler le point de terminaison pendant les longs rendus.
- Échéance stricte. Limitez toujours le temps d'attente total. Sans cela, une tâche bloquée occupe un worker indéfiniment. Choisissez la limite d'après votre temps de rendu réel le plus long, plus une marge.
- Séparez échec et timeout. Une tâche
failedest une erreur de génération qui mérite d'être signalée à l'utilisateur. Un timeout est une condition d'infrastructure qui mérite une nouvelle tentative ou une enquête séparée. Confondre les deux rend les post-mortems pénibles.
Dans un service web
N'exécutez pas cette boucle dans le handler de requête pendant que l'utilisateur attend. Soumettez, stockez l'identifiant de tâche, renvoyez immédiatement, et laissez un worker en arrière-plan interroger et livrer le résultat — via un webhook, une file d'attente ou une mise à jour de ligne surveillée par le frontend. La boucle ci-dessus est une préoccupation de worker, pas une préoccupation HTTP.
Diagnostiquer les échecs courants
La plupart des échecs se rangent dans trois catégories. Déterminez d'abord la catégorie, puis la cause précise.
Catégorie 1 : échec de validation des entrées
Symptôme : une 4xx immédiate à la soumission, avant tout rendu.
Diagnostiquez dans cet ordre :
- L'URL de l'image est-elle accessible ? Récupérez-la vous-même depuis le même réseau. Les URL signées expirées et les buckets privés sont la première cause.
- Le format est-il pris en charge ? Réencodez dans un format standard plutôt que d'en débattre.
- La première et la dernière frame sont-elles cohérentes ? Des ratios d'aspect différents ou des scènes très dissemblables se manifestent souvent par des erreurs de validation ou des problèmes de qualité.
- Avez-vous ajouté un champ au mauvais nom ? Les clés inconnues sont généralement rejetées et non ignorées. Comparez avec la référence du modèle.
Catégorie 2 : paramètres incompatibles
Symptôme : la requête est rejetée à cause d'un paramètre, ou la sortie ignore votre configuration.
- Résolution ou durée non prise en charge. N'utilisez que les valeurs de la documentation ; les nombres arbitraires sont une cause fréquente de rejet.
- Identifiant de modèle mal orthographié. C'est une chaîne fixe — copiez-la, ne la retapez pas.
- Erreur d'imbrication. Un paramètre de premier niveau placé dans
input, ou inversement, produit des erreurs déroutantes. Référez-vous à la structure de requête du chapitre 3.
Catégorie 3 : timeouts de polling et échecs de tâche
Symptôme : la tâche est acceptée mais n'atteint jamais un état terminal de réussite.
- Vérifiez que vous interrogez le bon identifiant. Les erreurs de copier-coller entre tâches dans un script de traitement par lots sont étonnamment fréquentes.
- Vérifiez que l'état progresse réellement. Journalisez l'état à chaque polling pour voir si la tâche avance ou stagne.
- Distinguez échec API et échec de génération. Si la requête de polling elle-même échoue, c'est un problème de transport. Si la tâche rapporte
failed, lisez le corps d'erreur — il pointe généralement vers l'entrée qui a posé problème. - Relancez le test de fumée
curlminimal. Si le test de fumée échoue aussi, le problème vient des identifiants ou du service ; s'il réussit, le problème vient de votre corps de requête.
Posture générale de débogage
Journalisez trois choses pour chaque tâche : le corps de requête exact, l'identifiant de tâche renvoyé, et l'état final avec le corps d'erreur. Avec ces trois éléments, presque chaque incident se diagnostique en cinq minutes au lieu d'un après-midi. En cas de doute, réduisez la requête à la forme minimale du chapitre 3 et ajoutez les champs un par un jusqu'à ce que ça casse — le dernier champ ajouté est le coupable.
Articles similaires
Voir tous les articles →-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage
-
Tutoriel
gemini-4-neon 实战应用场景 : 5 cas d'usage à forte valeur et points clés d'intégration
-
Tutoriel
Comment appeler seedance-2.5-flash text-to-video via l'API HiAPI (curl et Python)
Un exercice pratique de requête fonctionnelle pour les développeurs : endpoint, paramètres, gestion des tâches asynchrones, avec des exemples exécutables en curl et Python