Blog

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

Nov 19, 2026
Image de couverture : des flèches larges imbriquées sur fond indigo profond avancent par paliers, avec un bord avant pêche, formant une composition géométrique évoquant un flux de signal.
Sur cette page

Ce que seedance-2.5-flash/text-to-video vous apporte

seedance-2.5-flash/text-to-video est un endpoint de génération de vidéo à partir de texte sur l'API HiAPI. Vous envoyez une invite textuelle décrivant la scène cible et le modèle renvoie la vidéo générée. La convention est aussi simple que cela : du texte en entrée, une vidéo en sortie.

La génération vidéo prenant plus de temps qu'une complétion de chat classique, cet endpoint est asynchrone. Un appel unique ne bloque pas en attendant que la vidéo soit prête : il crée une tâche de génération, et vous récupérez le résultat une fois que la tâche a atteint un état terminal. Si vous avez déjà intégré une API média de longue durée, cette forme vous sera familière : soumettre, conserver l'identifiant de tâche, puis récupérer le résultat.

Votre travail d'intégration se décompose donc en trois points : construire une requête de soumission valide, persister l'ID de tâche et récupérer de manière fiable la vidéo terminée. Ce tutoriel parcourt ces trois étapes avec du code curl et Python exécutable, puis explique la validation des paramètres, le choix entre interrogation et callback, ainsi que les modes d'échec que rencontrent la plupart des premières intégrations.

Si vous construisez un pipeline qui transforme par programmation des invites en courts extraits vidéo — outil de contenu, backend de prototype ou service de génération interne — ce guide est fait pour vous. Si vous avez besoin d'une réponse synchrone, ou si vous cherchez la génération d'images plutôt que de vidéos, un autre endpoint conviendra mieux. Si cela correspond à votre cas d'usage, poursuivez avec les prérequis.

Prérequis et obtention de la clé API

Avant d'envoyer votre première requête, vérifiez trois choses.

Compte HiAPI et clé API

Toutes les requêtes vers cet endpoint sont authentifiées avec une clé API liée à votre compte HiAPI. Créez la clé dans le panneau de contrôle de votre compte et évitez de la committer dans un gestionnaire de versions. Les exemples ci-dessous la lisent depuis une variable d'environnement, ce qui vous permet de la coller directement dans un terminal ou un script sans modifier la clé en ligne :

export HIAPI_API_KEY="your_api_key_here"

Un client capable d'envoyer des requêtes HTTPS

Pour la partie curl, il vous faut curl, fourni par défaut sur macOS et la plupart des distributions Linux. Pour la partie Python, il vous faut Python 3 et la bibliothèque requests (pip install requests). Aucun SDK propre au fournisseur n'est nécessaire : l'endpoint est du HTTPS ordinaire avec un corps JSON, donc n'importe quel client HTTP convient, de fetch en Node à httpx en Python.

Un moyen de conserver l'état entre les requêtes

La génération étant asynchrone, il vous faut un endroit où stocker l'identifiant de tâche renvoyé par l'appel de soumission — une ligne de base de données, une file de tâches ou un fichier JSON pendant les tests. Si vous prévoyez d'utiliser des callbacks plutôt que l'interrogation, il vous faut également un endpoint HTTPS accessible par HiAPI.

Une fois la clé et un client à disposition, vous pouvez soumettre une requête.

Envoyer une première requête fonctionnelle avec curl

L'appel de soumission est un POST avec un corps JSON. Le chemin exact de l'endpoint et le nom de l'en-tête d'authentification sont documentés sur la page du modèle — utilisez ces valeurs telles quelles, sans les déduire d'une autre API. La structure de l'appel est la suivante :

curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
  }'

Quelques précisions sur chaque partie :

  • Méthode et chemin. POST crée une nouvelle tâche de génération. Le chemin identifie le modèle ; vérifiez-le sur la page du modèle avant de le copier dans votre propre configuration.
  • En-têtes. L'en-tête Authorization transporte votre clé, et Content-Type: application/json indique au serveur comment analyser le corps de la requête.
  • Corps de la requête. Au minimum, envoyez une chaîne prompt. L'invite est l'entrée créative — tout ce que le modèle rend en provient — soyez donc explicite sur le sujet, le mouvement, l'éclairage et le comportement de la caméra.

Si la requête est acceptée, la réponse contient un objet tâche. Vous n'obtenez pas immédiatement l'URL de la vidéo. Extrayez l'identifiant de tâche de la réponse et sauvegardez-le. Le nom exact du champ fait partie du schéma de réponse documenté sur la page du modèle ; traitez-le comme la source de vérité unique et n'encodez pas en dur des suppositions dans votre client avant d'avoir vu une vraie réponse.

Vous pouvez d'abord inspecter la réponse brute avec curl, puis porter le même appel dans le code une fois sa forme comprise.

Choisir les paramètres : invite, résolution et durée

Seul prompt est strictement obligatoire, mais plusieurs paramètres facultatifs déterminent le résultat et le coût de la requête. Définissez-les de manière réfléchie plutôt que d'accepter aveuglément les valeurs par défaut.

Invite

L'invite est le paramètre qui a le plus d'impact. Rédigez-la comme un brief à un cadreur : sujet, action, environnement, éclairage et style de caméra. « A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field » fournit bien plus d'informations au modèle que « a city ». Respectez la limite de longueur documentée sur la page du modèle.

Résolution

Une résolution plus élevée signifie plus de détails et un fichier de sortie plus volumineux, ainsi qu'un temps de génération potentiellement plus long. La génération vidéo est généralement facturée à la durée de sortie, mais vérifiez la base de facturation actuelle et les éventuels paliers de résolution sur le panneau des prix et dans la documentation du modèle plutôt que de faire des suppositions. Choisissez la résolution la plus basse qui satisfait votre objectif de livraison — un suréchantillonnage en post-production est souvent moins coûteux que de tout générer en qualité maximale.

Durée

La durée contrôle le nombre de secondes de vidéo que le modèle génère, et influence généralement à la fois la latence et le coût. Les clips courts conviennent mieux à l'itération : affinez l'invite sur une durée courte jusqu'à ce que le mouvement soit correct, puis régénérez avec la durée finale.

Validation avant envoi

Avant de brancher des valeurs dans du code de production, consultez la page du modèle pour connaître les plages autorisées de chaque paramètre — durées permises, résolutions prises en charge et éventuelles valeurs d'énumération. Validez ensuite côté client : rejetez les durées hors plage et les valeurs de résolution inconnues avant que la requête ne quitte votre processus. Vous transformez ainsi une catégorie d'erreurs de validation côté serveur en échec immédiat et peu coûteux dans vos propres journaux.

La même règle s'applique aux noms de paramètres. Copiez-les depuis la documentation ; une faute de frappe comme un underscore en trop dans un champ de durée est généralement rejetée ou silencieusement ignorée, et l'ignorance silencieuse est le bug le plus difficile à repérer.

Envoyer la même requête en Python

Voici le code de soumission équivalent en Python. Il lit la clé depuis une variable d'environnement, envoie le corps JSON, vérifie le code de statut et renvoie l'identifiant de tâche depuis les champs de réponse documentés.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def submit_video(prompt: str, **options) -> str:
    payload = {
        "prompt": prompt,
        **options,  # e.g. resolution="720p", duration=5
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    task_id = body["id"]  # confirm the field name on the model page
    return task_id


if __name__ == "__main__":
    task_id = submit_video(
        "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
    )
    print("submitted task:", task_id)

Ce code contient plusieurs choix délibérés :

  • Timeout. L'appel de soumission doit revenir rapidement, mais un timeout explicite empêche un socket bloqué de bloquer vos processus de travail.
  • raise_for_status(). Échouer immédiatement en cas d'erreur HTTP, plutôt que d'analyser un corps de réponse d'erreur comme une réponse de succès.
  • Options par mot-clé. Passer **options garde le site d'appel lisible, et ajouter resolution ou duration devient trivial une fois les noms exacts confirmés sur la page du modèle.
  • Renvoi de l'ID. La responsabilité de la fonction s'arrête à la soumission. Persistez cet ID dans un stockage durable — la section suivante s'en servira pour récupérer le résultat.

Dans un pipeline réel, considérez submit_video comme une étape d'un flux de travail piloté par une file : mettez-la en file, sauvegardez l'ID de tâche renvoyé avec votre enregistrement de tâche, et laissez un processus de travail distinct se charger de récupérer le résultat.

Gérer les résultats asynchrones : interrogation et callbacks

Après la soumission, vous avez un ID de tâche, mais pas encore de vidéo. Deux moyens comblent cet écart.

Interrogation

Interrogez l'endpoint de statut de la tâche à intervalle régulier jusqu'à ce que la tâche atteigne un état terminal, puis récupérez l'URL de sortie depuis la réponse de fin.

import time
import requests


def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",  # confirm path on the model page
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()
        state = task["status"]
        if state == "completed":
            return task
        if state == "failed":
            raise RuntimeError(task.get("error", "generation failed"))
        time.sleep(delay)
        delay = min(delay * 1.5, 15)  # gentle backoff, capped
    raise TimeoutError(f"task {task_id} did not finish in time")

Trois règles pratiques pour l'interrogation :

  • Rétroactivité. Commencez par un délai court et augmentez-le progressivement. Une interrogation continue à haute fréquence gaspille du quota et ajoute de la charge sans aucun bénéfice.
  • Plafond. Chaque boucle d'interrogation a besoin d'une échéance. La génération vidéo peut prendre du temps, mais une boucle non bornée finira par bloquer indéfiniment votre processus à cause d'une tâche coincée.
  • Distinguer les états. Traitez explicitement failed, pour qu'une mauvaise invite ne soit pas silencieusement prise pour un timeout.

Callbacks

Si vous enregistrez une URL de callback HTTPS, HiAPI peut vous notifier à la fin de la tâche, ce qui évite complètement l'interrogation. Deux règles rendent les callbacks sûrs et fiables :

  • Vérifier avant de faire confiance. Traitez le callback comme une entrée non authentifiée tant que sa signature ou son origine n'a pas été vérifiée via le mécanisme documenté par la plateforme.
  • Rester idempotent. Un callback peut être livré plusieurs fois. Utilisez l'ID de tâche comme clé du gestionnaire et rendez le traitement des livraisons répétées sans effet — stockez le résultat une seule fois et acquittez les livraisons en double.

Quelle que soit la méthode choisie, la récupération du résultat est idempotente : récupérer l'URL du résultat d'une tâche terminée doit renvoyer la même vidéo, donc un nouvel essai après une erreur réseau est sans danger.

Erreurs courantes et comment les corriger

La plupart des échecs se rangent dans quelques catégories. Avant de supposer l'existence d'un comportement non documenté, passez en revue cette liste.

Échec d'authentification

Un 401 ou un 403 signifie presque toujours que la clé est absente, mal formée ou expirée. Vérifiez que l'en-tête Authorization est présent, que le schéma d'authentification correspond exactement à la documentation et que la variable d'environnement contient bien la clé — une chaîne vide produit un échec déroutant mais bien lié à l'authentification.

Validation refusée

Un 4xx accompagné d'un message de validation signifie que le serveur a refusé vos paramètres. Relisez les plages autorisées sur la page du modèle et confirmez les noms de paramètres caractère par caractère. Si la durée ou la résolution sort de la plage, la correction est la validation côté client décrite plus haut — échouer rapidement dans votre propre code plutôt que d'aller-retour vers le serveur.

Tâche bloquée dans un état non terminal

Si l'interrogation ne voit jamais completed ni failed, soit la tâche est encore en cours, soit votre boucle interroge un ID de tâche erroné. Journalisez l'ID soumis et l'ID interrogé, puis comparez-les. Votre boucle doit également imposer une échéance ; quand elle se déclenche, exposez l'ID de tâche plutôt que de réessayer aveuglément.

Résultat non reçu après le callback

Si vous dépendez des callbacks, vérifiez que votre endpoint est publiquement accessible en HTTPS, qu'il renvoie rapidement un statut de succès au lieu d'exécuter un travail lourd en ligne, et que les livraisons répétées sont traitées de manière idempotente. Si le gestionnaire de callback renvoie une erreur lors de la deuxième livraison d'une même tâche, cela ressemblera à une perte de résultat.

Soumission répétée de la même tâche

Si votre processus de travail réessaie l'appel de soumission après un timeout, il peut créer des tâches en double. Avant d'appeler l'endpoint, enregistrez une clé de requête client ou un ID de tâche dans votre propre base de données, et vérifiez-la avant un nouvel essai, afin que la soumission reste idempotente de votre côté.

Principe général : en cas d'échec, lisez d'abord le corps de la réponse d'erreur et la documentation du modèle, puis modifiez le code. Si une valeur ou un champ n'est pas documenté, évitez de supposer qu'il existe — vérifiez sur la page du modèle et adaptez la requête en conséquence.

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