Blog

Tutoriel

Comment appeler l'API image-vers-vidéo seedance-2.5 : exemples curl et Python disponibles

Nov 12, 2026
Illustration de couverture abstraite : des panneaux de verre translucides qui se chevauchent projetant des bandes d'un bleu froid sur un fond gris pâle, aspect plat et architectural.
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 :

  • prompt décrit le mouvement. Restez bref et précis ; de longues listes d'adjectifs diluent souvent l'instruction.
  • first_frame_image est requis pour l'image-vers-vidéo. last_frame_image est 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 failed et cancelled comme 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 →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API