Comment utiliser seedance-2.0-fast via l'API hiapi : curl, Python et requêtes exécutables

Ce guide présente la requête minimale pour générer une vidéo avec seedance-2.0-fast, tous les champs d'entrée réellement acceptés par ce modèle, ainsi que la manière d'attendre le résultat par interrogation répétée (polling) ou par callback. Chaque structure de requête et chaque message d'erreur ci-dessous ont été vérifiés sur l'API réelle, vous pouvez donc copier le code tel quel.

Ce que vous allez construire et ce qu'il vous faut

Un seul objectif : envoyer un prompt textuel et récupérer une URL MP4 téléchargeable. seedance-2.0-fast est la version optimisée pour la vitesse de Seedance 2.0 — elle sacrifie la résolution maximale (plafonnée à 720p) au profit d'une génération plus rapide, ce qui la rend idéale pour les aperçus, les boucles d'itération et les grands lots de courts clips vidéo.

Il vous faut une seule chose : une clé API hiapi. Récupérez-la depuis votre tableau de bord ; son format ressemble à sk-.... Tous les modèles vidéo (y compris celui-ci) sont servis via un point de terminaison de tâches asynchrone unifié : vous POST /v1/tasks pour créer une tâche, puis vous récupérez le résultat via l'id de la tâche. La vidéo n'a pas de mode synchrone.

Le prix actuel d'un clip se trouve sur la page des tarifs (ce modèle vient d'être mis en ligne, fiez-vous donc à cette page et ne vous fiez à aucun chiffre trouvé dans des articles de blog).

Exemple minimal exécutable (curl)

Créer la tâche :

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "input": {
      "prompt": "Un bateau en papier dérive sur une rue détrempée par la pluie au crépuscule, cinématographique, lent travelling avant",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

L'id de la tâche se trouve dans data.taskId de la réponse :

{
  "data": {
    "taskId": "task_abc123..."
  }
}

Interrogez la tâche à intervalles réguliers jusqu'à ce que son état devienne terminal :

curl "https://api.hiapi.ai/v1/tasks/task_abc123..." \
  -H "Authorization: Bearer sk-YOUR_KEY"

Lorsque data.status vaut "success", l'URL de la vidéo se trouve dans data.output[0].url. Cette URL est signée et expire — téléchargez le fichier immédiatement, ne faites pas de lien direct (hotlink) :

curl -o clip.mp4 "<the output url>"

Tous les champs d'entrée (vérifiés)

Seul prompt est obligatoire. Tout champ absent de ce tableau est rejeté avec un 400 — le schéma n'autorise pas de propriétés supplémentaires.

Champ	Type	Obligatoire	Valeurs acceptées
prompt	string	oui	longueur minimale de 3 caractères
duration	entier	non	4–15 (secondes)
resolution	string	non	480p, 720p
aspect_ratio	string	non	1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive

Deux points méritent une attention particulière :

• duration est un entier, pas une chaîne. Envoyer "duration": "5" échouera à la validation, avec l'erreur duration: got string, want integer.
• Pas d'entrée image. seedance-2.0-fast ne prend en charge que la génération texte-vers-vidéo ; des champs comme image_urls sont rejetés par le schéma. Si vous avez besoin de la génération image-vers-vidéo, consultez le guide du workflow API image-vers-vidéo pour connaître les modèles qui prennent en charge cette fonctionnalité.

Le même flux en Python

Pas besoin de SDK — requests suffit :

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, duration: int = 5,
                resolution: str = "720p", aspect_ratio: str = "16:9") -> str:
    payload = {
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    r = requests.post(API_BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task(
    "Une barista verse un latte art dans un café baigné de soleil, faible profondeur de champ"
)
task = wait_task(task_id)
video_url = task["output"][0]["url"]

# L'URL est signée et expire — persistez immédiatement les octets.
with open("clip.mp4", "wb") as f:
    f.write(requests.get(video_url, timeout=120).content)
print("saved clip.mp4")

Considérez tout état autre que success / fail comme « toujours en cours » — ainsi, la boucle reste robuste même si les noms des états intermédiaires changent à l'avenir.

Considérations pour la production

Utiliser un callback au lieu du polling

Pour tout scénario au-delà d'un script, enregistrez un callback lors de la création de la tâche et sautez complètement le polling :

{
  "model": "seedance-2.0-fast",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

Avec "when": "final", lorsque la tâche atteint son état terminal, votre point de terminaison reçoit exactement un POST. Le polling convient aux CLI et aux notebooks ; à grande échelle, les callbacks sont préférables (aucune requête inutile et aucune latence due à l'intervalle de polling). Si votre hook semble ne pas se déclencher, consultez le guide de dépannage des callbacks — il s'agit presque toujours d'un problème d'accessibilité de l'URL ou d'un gestionnaire qui renvoie une réponse non 2xx.

Idempotence

La création d'une tâche n'est pas gratuite, il faut donc éviter les soumissions en double de votre côté : faites correspondre chaque événement métier à au plus un appel POST /v1/tasks (par exemple, enregistrez le taskId associé à votre ligne de commande/tâche avant de réessayer). Si votre processus plante après avoir créé la tâche, vous pouvez reprendre en relisant le taskId stocké et en reprenant GET /v1/tasks/<id> — la tâche continue de s'exécuter côté serveur, que vous fassiez du polling ou non.

Les erreurs que vous rencontrerez réellement

Symptôme	Signification	Correction
400 avec error_code: "INVALID_REQUEST"	L'entrée n'a pas passé la validation du schéma ; message indique le champ concerné, par exemple duration: maximum: got 20, want 15	Corrigez ce champ ; seuls les quatre champs du tableau ci-dessus sont autorisés
401 avec error.code: "permission_denied"	Clé invalide, ou valide mais non activée pour ce modèle	Vérifiez la clé dans le tableau de bord ; les permissions de modèle sont définies par clé
404 avec "task not found" lors du GET	Id de tâche erroné ou n'appartenant pas à ce compte	Utilisez le taskId renvoyé à la création, et depuis le même compte
État de la tâche "fail" avec un objet error	La génération elle-même a échoué	Lisez error.code/error.message ; ajustez le prompt et réessayez

Notez les deux formats d'erreur : les erreurs de validation placent message au niveau supérieur, tandis que les erreurs d'authentification sont imbriquées sous error. Si vous écrivez un middleware générique, vous devez gérer les deux cas.

Quand utiliser seedance-2.0-fast

Si vous avez besoin d'une sortie 1080p ou 4K, utilisez plutôt le seedance-2.0 complet — même point de terminaison, même flux, plafond de résolution plus élevé (et il exige de spécifier explicitement aspect_ratio). Pour une comparaison plus complète de la gamme Seedance avec les autres modèles vidéo de la plateforme, consultez la comparaison des modèles vidéo. La référence complète des paramètres de chaque modèle se trouve dans la documentation, et la page du modèle suit l'état actuel des capacités et de la tarification.

Questions fréquentes

Quelles résolutions seedance-2.0-fast prend-il en charge ? 480p et 720p. C'est le prix de la vitesse — le seedance-2.0 complet atteint jusqu'à 1080p et 4k avec le même flux /v1/tasks.

Puis-je faire de la génération image-vers-vidéo avec seedance-2.0-fast ? Non. Le schéma d'entrée n'accepte que prompt, duration, resolution et aspect_ratio ; les champs image sont rejetés par une erreur de validation. Pour les options de génération image-vers-vidéo sur hiapi, consultez le guide du workflow image-vers-vidéo.

Quelle peut être la durée de la vidéo générée ? duration accepte un entier de 4 à 15 secondes. Les valeurs hors de cette plage échouent à la validation avant la création de la tâche (les requêtes rejetées ne sont pas facturées).

Faut-il faire du polling ou utiliser un callback ? Pour les scripts et les faibles volumes de concurrence, un polling toutes les ~5 secondes suffit. À l'échelle de la production, passez callback: {"url": ..., "when": "final"} à la création pour que hiapi vous pousse l'état terminal — une seule requête au lieu de dizaines.

Pourquoi une clé qui fonctionne avec d'autres modèles renvoie-t-elle ici 401 permission_denied ? L'accès aux modèles est limité par clé. Un 401 avec permission_denied sur ce modèle signifie que la clé existe mais n'est pas activée pour seedance-2.0-fast — vérifiez les permissions de modèle de cette clé dans le tableau de bord.

Quelle est la durée de validité de l'URL de sortie ? C'est une URL signée qui expire. Téléchargez le MP4 dès que la tâche réussit et stockez-le vous-même ; n'intégrez pas l'URL de sortie brute dans un emplacement destiné à perdurer.