Tutoriel
Comment appeler l'API image-vers-vidéo seedance-2.5 : exemples curl et Python disponibles
Sur cette page
Ce que vous apporte le point de terminaison image-vers-vidéo seedance-2.5
seedance-2.5 image-vers-vidéo est un point de terminaison de modèle asynchrone sur HiAPI qui transforme une ou deux images statiques en un court clip vidéo. Vous lui envoyez une image (ou une paire d'images servant respectivement de début et de fin de mouvement), vous décrivez le changement attendu, et la plateforme renvoie une tâche qui se résout en une URL de fichier vidéo une fois la génération terminée.
Dans une pile de génération vidéo typique, ce point de terminaison se situe à la couche « faire bouger une image statique ». Vous disposez déjà des images sources — visuels produit, rendus de personnages, images de storyboard — et vous voulez du mouvement, et non une nouvelle image. Comme l'appel est asynchrone, votre travail consiste à soumettre la tâche, conserver l'identifiant de tâche et interroger continuellement jusqu'à ce que le résultat soit prêt. Ce modèle soumettre-puis-interroger est commun aux points de terminaison de génération longue durée de HiAPI, de sorte que le client que vous écrivez ici peut être réutilisé pour d'autres modèles.
Ce point de terminaison propose également des options d'audio natif, ce qui est important si votre pipeline a besoin d'un clip avec du son plutôt que d'une séquence muette à laquelle ajouter une musique plus tard. Si vous avez besoin de mouvements de caméra précis à l'image près ou d'animations bouclables, l'image-vers-vidéo avec première et dernière images explicites est généralement le choix le plus contrôlable sans monter une scène 3D.
Prérequis et authentification
Avant le premier appel, préparez trois choses.
1. Une clé API HiAPI
Chaque requête est authentifiée avec votre clé, envoyée sous forme de jeton bearer dans l'en-tête Authorization. Ne la validez pas dans la gestion de sources — lisez-la depuis une variable d'environnement afin que le même script fonctionne en local comme en CI.
export HIAPI_API_KEY="your_key_here"
2. Des images sources accessibles par l'API
L'entrée image est une URL. Hébergez l'image à un emplacement accessible par le service — stockage objet avec URL signée, CDN ou toute adresse HTTPS publique. Si vous ne souhaitez pas exposer l'image publiquement, générez une URL signée de courte durée plutôt que de rendre le bucket public.
Pour un flux de travail première/dernière image, vous avez besoin d'une image (première image seulement) ou de deux images (première et dernière).
3. Un client HTTP
Tout outil capable d'envoyer du JSON convient : curl pour un test de fumée rapide, requests ou httpx en Python, fetch en Node. Vous n'avez pas besoin de SDK spécifique.
L'URL de base, le chemin et les noms de champs spécifiques au modèle se trouvent sur la page du modèle dans la console HiAPI ; utilisez ces valeurs telles quelles dans les exemples ci-dessous. Une fois la clé et l'URL d'image en main, vous pouvez soumettre.
Entrée première image et entrée dernière image
Les deux entrées d'image contrôlent des extrémités différentes du clip, et le choix modifie votre degré de contrôle sur le mouvement.
Première image uniquement. Vous fournissez une image et le modèle génère à partir d'elle vers l'avant. C'est le bon choix lorsque vous voulez que le modèle invente le mouvement : un portrait qui se tourne lentement, un produit qui pivote, un paysage dont les nuages dérivent. Vous renoncez à la certitude sur l'endroit où se termine le clip, mais vous gagnez en liberté créative et n'avez besoin que d'un seul élément.
Première et dernière images. Vous fournissez deux images et le modèle génère un chemin entre elles. C'est le bon choix lorsque les extrémités comptent : un logo qui s'assemble en composition finale, un personnage qui passe de la pose A à la pose B, un objet qui glisse de la gauche vers la droite du cadre. Fournir une dernière image contraint le mouvement, ce qui signifie généralement moins de surprises et, si vous prévoyez de lire le clip en boucle, une meilleure bouclabilité.
Une règle pratique : si vous pouvez décrire le clip comme « quelque chose arrive à cette image », utilisez uniquement la première image. Si vous pouvez le décrire comme « cette image devient celle-là », fournissez les deux. Lorsque vous fournissez les deux, gardez-les cohérentes en composition, ratio d'aspect et éclairage — une paire d'images discordante force le modèle à gérer un saut qui ressemble à un bug.
Votre prompt doit compléter les images, pas les contredire. Décrivez le mouvement, pas le contenu statique que le modèle voit déjà.
Soumettre la première requête avec curl
La requête suivante soumet une tâche image-vers-vidéo. Remplacez le chemin du point de terminaison, l'identifiant de modèle et les noms de champs par les valeurs affichées sur la page du modèle image-vers-vidéo seedance-2.5 dans la console HiAPI, et insérez vos propres URL d'images.
curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5/image-to-video",
"prompt": "La caméra avance lentement pendant que le sujet se tourne vers la lumière",
"first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
"last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
}'
Quelques points à noter concernant la structure de la requête :
promptdécrit le mouvement. Restez bref et précis ; de longues listes d'adjectifs diluent souvent l'instruction.first_frame_imageest requis pour l'image-vers-vidéo.last_frame_imageest facultatif — supprimez complètement ce champ pour une génération à première image seulement.- Si vous avez besoin d'options audio, ce sont des champs supplémentaires dans le même corps JSON (voir plus bas).
La réponse est un objet de tâche contenant un identifiant et un statut. Conservez l'identifiant ; il est nécessaire à chaque interrogation. Si l'appel renvoie une erreur d'authentification ou de validation, vérifiez d'abord les en-têtes et l'URL de l'image, puis réessayez.
La même requête en Python
Voici le code de soumission équivalent en Python, restructuré pour faciliter la capture de l'identifiant de tâche.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(first_frame, last_frame=None, prompt="", audio=False):
payload = {
"model": "seedance-2.5/image-to-video",
"prompt": prompt,
"first_frame_image": first_frame,
}
if last_frame:
payload["last_frame_image"] = last_frame
if audio:
payload["audio"] = True
resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()
return data["task_id"], data
task_id, raw = submit_video(
first_frame="https://your-cdn.example.com/frame-01.jpg",
last_frame="https://your-cdn.example.com/frame-02.jpg",
prompt="La caméra avance lentement pendant que le sujet se tourne vers la lumière",
)
print(task_id)
Deux habitudes méritent d'être prises tôt. Premièrement, définissez un timeout explicite sur l'appel de soumission — une requête suspendue doit échouer rapidement plutôt que bloquer votre worker. Deuxièmement, conservez la réponse brute pendant le développement. Le champ contenant l'identifiant de tâche peut différer de task_id selon la version du point de terminaison ; imprimer une fois le JSON brut épargne un cycle de débogage.
Interroger la tâche asynchrone jusqu'à ce que la vidéo soit prête
La génération image-vers-vidéo prend plus de temps qu'une requête HTTP ne devrait rester ouverte, c'est pourquoi la plateforme adopte un cycle de vie soumettre-puis-interroger. La soumission renvoie un identifiant de tâche ; vous interrogez ensuite périodiquement le point de terminaison de tâche jusqu'à ce que son statut atteigne un état terminal.
import time
import requests
def wait_for_video(task_id, interval=5, max_wait=600):
url = f"{BASE_URL}/<task-path>/{task_id}"
deadline = time.time() + max_wait
while time.time() < deadline:
resp = requests.get(url, headers=HEADERS, timeout=30)
resp.raise_for_status()
task = resp.json()
status = task.get("status")
if status == "succeeded":
return task["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")
Concevez l'interrogation autour de quatre règles :
- Interrogez à un intervalle modéré. Cinq secondes est une valeur par défaut raisonnable. Marteler le point de terminaison ne rend pas la vidéo plus vite.
- Fixez toujours une échéance. Une tâche peut échouer ou rester en file plus longtemps que prévu ; une boucle sans limite transforme un problème temporaire en worker bloqué.
- Traitez
failedetcancelledcomme des états terminaux. Exposez le champ d'erreur au lieu de réessayer indéfiniment la même tâche. - Utilisez un backoff pour l'interrogation continue. Si vous interrogez de nombreuses tâches en parallèle, augmentez progressivement l'intervalle pour éviter les pics de trafic.
En production, interrogez depuis un worker en arrière-plan ou une file d'attente, et non à l'intérieur d'un gestionnaire de requête web. Le résultat est une URL vidéo ; téléchargez-la rapidement et copiez-la dans votre propre stockage, car les URL de ressources générées ne sont généralement pas permanentes.
Gérer le drapeau d'audio natif
seedance-2.5 peut générer des clips avec audio natif ; ce contrôle est un champ de requête aux côtés des entrées d'image et du prompt — et non un point de terminaison séparé. Le nom exact du champ et les valeurs acceptées figurent sur la page du modèle ; l'assistant Python ci-dessus l'illustre via un booléen audio.
L'activer ou non dépend de la façon dont le clip sera consommé.
Demandez de l'audio lorsque : la sortie est destinée directement à l'audience — publication sociale, aperçu, démonstration — et vous voulez que le clip soit complet sans second montage. L'audio natif aide aussi les relecteurs à juger le rythme, car le son rend le timing du mouvement plus lisible.
Ignorez l'audio lorsque : votre pipeline superpose sa propre musique, le clip part dans un outil de composition ou de montage, ou vous prévoyez de générer de nombreuses variantes pour ne mettre en musique que la version finale retenue. Une génération silencieuse garde le matériel neutre et évite les problèmes de synchronisation ultérieurs.
Une note pratique pour circonscrire le sujet : traitez l'audio comme une décision par requête, et non comme un réglage global. Comme montré plus haut, un unique assistant acceptant un drapeau audio permet au même chemin de code de servir à la fois le traitement par lots en arrière-plan silencieux et le rendu final soigné.
Si le drapeau est présent mais que le résultat est silencieux, vérifiez d'abord que la valeur est sérialisée comme prévu — la chaîne "true" contre le booléen true est une erreur courante — avant de supposer que le modèle l'a ignoré.
Points d'échec courants et prochaines étapes
La plupart des problèmes d'intégration initiaux se rangent dans quatre catégories.
Entrées inaccessibles au service
Une URL qui fonctionne dans votre navigateur peut échouer côté service : buckets privés, liens expirés ou hôtes bloquant les agents utilisateur non navigateur. Utilisez une URL signée dont la durée de vie couvre l'ensemble de la génération, et vérifiez que l'image se charge depuis une machine extérieure à votre réseau.
Images discordantes
Lorsque la première et la dernière image diffèrent en ratio d'aspect, en cadrage ou en température de couleur, le modèle doit réconcilier ce saut. Avant de soumettre, pré-traitez la paire d'images aux mêmes dimensions et à un étalonnage proche.
Noms de champs ou identifiant de modèle erronés
Les exemples ici utilisent la structure de requête de la page du modèle ; copiez tels quels depuis la console les noms de champs et la chaîne de modèle, plutôt que de vous fier à la mémoire ou à un ancien extrait. Une faute de frappe dans un nom de champ est souvent ignorée silencieusement plutôt que rejetée.
Interrogation qui ne se termine jamais
Si votre boucle expire à répétition, journalisez chaque valeur de statut observée. Voir une chaîne de statut inattendue explique généralement le blocage — votre vérification d'état terminal ne correspond peut-être tout simplement pas à ce que renvoie l'API.
Une fois qu'un clip fonctionne de bout en bout, l'étape suivante naturelle est de traiter plusieurs images par lots via le même assistant de soumission et d'interrogation, d'ajouter des réessais avec backoff autour de la soumission, et d'écrire les résultats dans un stockage persistant. Vous trouverez les détails du point de terminaison, les champs de requête et la référence des paramètres sur la page du modèle image-vers-vidéo seedance-2.5, pour adapter le code ci-dessus à vos propres images.
Articles similaires
Voir tous les articles →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
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