Tutoriel
Comment appeler seedance-2.5-flash reference-to-video via l'API HiAPI (curl + Python)
Des requêtes fonctionnelles, un script Python exécutable, et comment gérer l'interrogation des tâches asynchrones
Sur cette page
Ce que signifie concrètement la génération vidéo à partir de références
La génération vidéo à partir de références est un mode de génération : vous fournissez au modèle deux choses à la fois — une invite textuelle décrivant le mouvement et la scène, et une ou plusieurs références qui ancrent le contenu visuel. L'invite porte l'intention (« travelling avant lent, le personnage se retourne et sourit »), les références portent l'identité et l'apparence (un personnage, un produit, un style visuel).
Le point de terminaison de ce flux de travail est seedance-2.5-flash/reference-to-video, proposé via l'API unifiée de HiAPI. Vous envoyez le modèle, l'invite et les références ensemble dans un seul corps de requête. Aucune étape d'envoi séparée à orchestrer, aucun registre par référence à maintenir.
Conséquence pratique : il s'agit d'une opération de longue durée. Le rendu d'une courte vidéo reste bien plus long qu'une complétion de texte, c'est pourquoi l'API traite cet appel comme une tâche asynchrone. Votre requête crée la tâche ; un second appel récupère son résultat. Cette forme « soumettre puis interroger » est le point le plus important de votre conception, et c'est la direction que construit le reste de ce tutoriel.
Tout ce qui suit reste dans l'interface HiAPI : une URL de base, un en-tête d'authentification, une famille de points de terminaison.
Avant d'envoyer la première requête
Trois choses doivent être prêtes avant le premier appel.
1. La clé d'API
Créez la clé dans la console HiAPI et tenez-la à l'écart du contrôle de version. Les exemples suivants la lisent depuis une variable d'environnement :
export HIAPI_API_KEY="your_key_here"
Si vous n'êtes pas sûr du format actuel de la clé ou des conventions d'en-tête, consultez la documentation de l'API de la plateforme dans la console — ne devinez pas, et ne codez pas la clé en dur dans un script que vous pourriez partager.
2. L'URL de base et l'en-tête d'authentification
Tous les appels vont vers l'URL de base HiAPI et portent votre clé dans l'en-tête Authorization. Définissez-la une fois dans une variable pour garder chaque requête cohérente :
export HIAPI_BASE_URL="https://api.hiapi.ai"
Utilisez l'URL de base exactement telle qu'indiquée dans la documentation de votre compte — une barre oblique finale non concordante est une cause fréquente de 404 déroutants.
3. Le point de terminaison du modèle
Vous ciblez seedance-2.5-flash/reference-to-video. Référencez-le dans le corps de la requête avec cet identifiant, plutôt que de l'intégrer dans le chemin, afin que changer de modèle ne demande qu'une seule ligne plus tard.
Vous devez également rendre vos références accessibles par URL (ou sous la forme que précise la documentation du point de terminaison). Hébergez-les et rendez-les publiquement accessibles avant de commencer — une URL de référence cassée est la cause la plus fréquente d'une tâche soumise avec succès mais qui échoue pendant la génération.
Une fois ces trois éléments en place, vous pouvez construire le corps de la requête.
Construire le corps de la requête avec les références
Le corps de la requête comporte trois parties conceptuelles : quel modèle, ce que vous voulez, et ce à quoi vous vous référez.
Le modèle
Définissez model sur seedance-2.5-flash/reference-to-video. Traitez-le comme un simple champ chaîne — pas d'encodage URL, pas de segment de chemin.
L'invite
Écrivez l'invite comme une description de plan, pas comme une liste de souhaits. Précisez le sujet, l'action, le comportement de la caméra et le rythme. « Une personne en veste rouge marche vers la caméra, plan moyen, travelling avant lent, lumière douce du jour » donne beaucoup plus d'informations au modèle que « une belle vidéo d'une personne ». Gardez l'invite cohérente avec les références fournies : si deux références montrent des personnages différents, précisez lequel domine.
Les références
Les références sont précisément ce qui distingue ce point de terminaison d'un appel classique de génération vidéo à partir de texte. Vous passez une ou plusieurs références qui définissent ce qui doit rester cohérent d'une image à l'autre. Quelques règles pratiques qui économisent des itérations :
- Utilisez le nombre minimal de références qui fixe l'identité. Une référence forte vaut souvent mieux que quatre références médiocres.
- Gardez les références cohérentes entre elles. Des angles ou des styles contradictoires font dériver la sortie.
- Privilégiez des sources propres et bien éclairées. Une référence recadrée, floue ou lourdement filtrée propage ces défauts.
- Vérifiez que chaque URL se résout avant de soumettre — récupérez-la vous-même d'abord.
La manière exacte dont les références sont adressées dans le corps de la requête (nom du champ tableau, structure de l'objet, types de références pris en charge) doit venir du schéma de requête du point de terminaison dans la documentation HiAPI. Construisez le corps d'après ce schéma, pas de mémoire ; ce schéma est la source de vérité des noms de champs, et une clé non concordante provoque un échec silencieux.
Validez le JSON localement avant que la requête n'atteigne le réseau (python -m json.tool body.json). Un corps mal formé est l'erreur la plus facile à détecter, et la plus pénible à déboguer à partir d'une trace de pile.
Une requête curl fonctionnelle
La commande suivante suit le schéma soumettre puis interroger : elle crée la tâche et affiche la réponse JSON contenant l'identifiant de tâche que vous utiliserez pour interroger.
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "Une personne en veste rouge marche vers la caméra, plan moyen, travelling avant lent, lumière douce du jour",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
Remplacez les URL de référence par vos propres ressources hébergées, et avant de faire dépendre ce code de la production, confirmez le chemin du point de terminaison et les noms de champs sur la page du modèle dans la documentation HiAPI — les détails du schéma font foi, cet extrait n'est qu'illustratif.
Ce qu'il faut regarder dans la réponse :
- Un id (ou identifiant de tâche/job) — capturez-le ; vous en aurez besoin à chaque interrogation.
- Un champ status indiquant que la tâche a été acceptée.
- Les éventuels avertissements concernant des références ignorées ou rejetées.
Pour le lisibilité, mettez-le en forme :
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
Conserver le corps de la requête dans body.json vaut ce petit effort supplémentaire : il se versionne proprement, se compare lisiblement et élimine les erreurs de guillemets shell du périmètre de débogage.
Le même appel en Python
Voici l'appel équivalent en Python, écrit pour être exécuté directement une fois les variables d'environnement définies. Il n'utilise que la bibliothèque standard, donc rien à installer.
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="Une personne en veste rouge marche vers la caméra, plan moyen, travelling avant lent, lumière douce du jour",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
Deux détails comptent plus qu'ils n'en ont l'air. Premièrement, timeout=60 — l'appel de soumission doit revenir vite, mais une connexion qui reste suspendue est pire qu'un échec rapide. Deuxièmement, result.get("id") gère le cas où la structure de la réponse est inattendue, au lieu de lever une KeyError dans votre chemin nominal.
Si vous préférez requests ou httpx, la conversion est directe : même URL, mêmes en-têtes, même corps JSON. La construction du corps est la partie à recopier ; le client HTTP est interchangeable.
Interroger la tâche asynchrone jusqu'à son achèvement
La génération vidéo n'est pas une requête que vous pouvez attendre. Vous soumettez, récupérez l'identifiant, puis vérifiez périodiquement l'état jusqu'à ce que la tâche atteigne un état terminal. Deux propriétés rendent cela sûr : l'interrogation coûte peu, et l'appel de soumission a déjà fait le travail coûteux.
La boucle
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
Une boucle plus serrée n'ira pas plus vite ; elle consumera seulement les limites de débit. Pour des tâches vidéo, un intervalle de cinq secondes est une valeur par défaut raisonnable.
Notes de conception
- Fixez toujours une échéance. Une tâche qui ne se termine jamais ne doit jamais suspendre indéfiniment le thread de la requête.
- Traitez un état inconnu comme « continuer d'attendre », pas comme un succès. Seul un succès explicite est un succès.
- N'interrogez pas depuis un gestionnaire de requête web. Soumettez dans le gestionnaire, renvoyez l'id de tâche au client, et laissez un processus d'arrière-plan interroger et persister le résultat.
- Persistez l'id de tâche et les transitions d'état, afin qu'un processus interrompu puisse reprendre au lieu de resoumettre et de payer deux fois le rendu.
Cette séparation soumettre puis interroger est précisément ce qui permet à un pipeline vidéo lent de se trouver derrière une API rapide.
Erreurs courantes et comment les corriger
Pratiquement chaque échec de la première heure entre dans l'une de quatre catégories. Vérifiez-les dans cet ordre.
1. Authentification
Symptôme : une réponse non autorisée ou interdite avant la création de toute tâche.
Vérifiez : HIAPI_API_KEY est-elle réellement renseignée dans le shell ou le processus qui exécute le script ? L'en-tête est-il exactement Authorization: Bearer <key> ? Chargez-vous la clé à l'import alors que le script l'attend plus tard ? Affichez les premiers caractères de la clé résolue (jamais la clé entière) et confirmez qu'elle n'est pas une chaîne vide.
2. Le chemin du point de terminaison
Symptôme : non trouvé, généralement immédiatement.
Vérifiez : exactement une barre oblique entre l'URL de base et le chemin — c'est pourquoi l'exemple Python appelle .rstrip("/"). Confirmez le chemin de génération et le chemin d'interrogation sur la page du modèle dans la documentation ; une URL d'interrogation à laquelle il manque le segment d'id de tâche renverra un 404 à chaque fois. Une barre oblique finale non attendue par le serveur produit le même symptôme.
3. Un corps de requête mal formé
Symptôme : une erreur de validation, ou une tâche acceptée puis échouant immédiatement.
Vérifiez : exécutez json.dumps(body) et inspectez-le. model correspond-il exactement à seedance-2.5-flash/reference-to-video ? Le champ des références est-il un tableau, et chaque entrée une URL sous forme de chaîne résoluble dans un navigateur ? Envoyez-vous Content-Type: application/json ? Passez le corps dans python -m json.tool pour écarter les erreurs de syntaxe avant qu'il n'atteigne le réseau.
4. L'état de la tâche
Symptôme : l'appel de soumission réussit, mais la tâche échoue ou ne se termine jamais.
Vérifiez : lisez le champ d'erreur dans la réponse d'état — il indique généralement la cause, le plus souvent une référence inaccessible ou non prise en charge. Si la tâche reste simplement bloquée, confirmez que vous interrogez le bon id et que la comparaison d'état de votre boucle couvre les états terminaux réellement renvoyés par l'API. Journalisez chaque transition d'état ; le dernier état avant l'échec est votre base de diagnostic.
Une règle qui raccourcit les quatre catégories de diagnostic : journalisez l'id de requête et l'id de tâche pour chaque appel. En cas d'incident, un id transforme un rapport d'erreur vague en une recherche précise.
Étapes suivantes
Vous disposez maintenant de la forme complète : construire le corps avec l'invite et les références, le soumettre, interroger jusqu'à l'état terminal, et gérer les quatre catégories d'échec courantes. À partir de là, les prochaines étapes naturelles relèvent de l'ingénierie, pas de l'API.
- Enveloppez la soumission dans des tentatives avec backoff pour les erreurs réseau transitoires, mais ne réessayez jamais une tâche qui a déjà un id — c'est un double rendu.
- Déplacez l'interrogation dans un processus d'arrière-plan ou une file d'attente, afin que la couche HTTP reste réactive et que les tâches survivent à un redémarrage du processus.
- Stockez l'id de tâche avec vos propres métadonnées de requête (invite, références, utilisateur demandeur), afin que les résultats restent traçables des mois plus tard.
- Validez les références avant de les accepter — récupérez chaque URL au moment où l'utilisateur la fournit, puis seulement engagez la tâche.
Pour le schéma de requête faisant foi, les types de références pris en charge et les détails actuels du point de terminaison, consultez la page du modèle de génération vidéo à partir de références seedance-2.5-flash sur HiAPI. Construisez d'après ce schéma, conservez la séparation soumettre puis interroger, et l'intégration restera d'une grande banalité — exactement ce que vous attendez d'un pipeline vidéo.
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