Blog

Tutoriel

Appeler muse-video-1.0/text-to-video via l'API HiAPI : guide curl et Python

Champs de requête, interrogation asynchrone et exemples de requêtes exécutables

Nov 13, 2026
Image de couverture brutaliste abstraite avec des plans de béton sous une lumière rasante, un champ gris chaud, des ombres bleu ardoise et une fine couture sauge.
Sur cette page

Avant d'envoyer : authentification, point de terminaison et identifiant du modèle

muse-video-1.0/text-to-video transforme un prompt textuel en un clip vidéo généré. Vous envoyez un prompt et quelques paramètres de contrôle, le service rend le clip, puis renvoie une URL ou une référence téléchargeable.

Le détail architectural essentiel : cet appel est asynchrone. Le rendu vidéo prend du temps, et l'API ne maintient pas votre connexion HTTP ouverte jusqu'à ce que le fichier soit prêt. Le flux se déroule donc en deux phases :

  1. Soumission — vous envoyez le prompt et les paramètres en POST. La réponse revient rapidement, avec un identifiant de tâche et un état initial.
  2. Interrogation — vous interrogez la tâche par identifiant à intervalles réguliers en GET, jusqu'à ce que son état devienne terminal (succès ou échec), puis vous récupérez le résultat.

Ce modèle « soumettre puis interroger » est le point le plus important à intégrer avant d'écrire du code. Il change la structure de votre application : la vidéo n'apparaît pas dans la réponse à la requête de soumission, et toute erreur que vous rencontrez appartient à une phase précise — soumission, validation, rendu ou récupération. Distinguer ces phases dans votre propre code (fonctions séparées, journaux distincts) facilitera l'application du reste de ce guide.

La chaîne de modèle transmise doit être exacte : muse-video-1.0/text-to-video. La forme vendor/model est la convention générale des points de terminaison de modèles HiAPI, et c'est sur elle que le routage de l'API détermine quel générateur appeler.

Construire la requête : prompt, durée et champs audio

Trois éléments doivent être prêts avant la première requête.

Clé API

Chaque requête doit être authentifiée par un bearer token. Stockez-le dans une variable d'environnement plutôt que dans le code source, afin d'éviter toute fuite dans les commits :

export HIAPI_API_KEY="your_key_here"

Envoyez-le via l'en-tête Authorization: Bearer $HIAPI_API_KEY. Si une requête échoue avec une erreur d'authentification, vérifiez d'abord cet en-tête — une faute de frappe dans le nom de variable, un espace en fin de chaîne ou une valeur absente du shell courant sont les causes les plus fréquentes.

URL de base

Tous les appels partagent une URL de base de la plateforme HiAPI. Utilisez la valeur actuelle indiquée dans le tableau de bord du compte ou la référence API, ne la copiez pas depuis un ancien extrait de code ; conservez-la dans une variable pour ne devoir la modifier qu'à un seul endroit.

Identifiant du modèle

La chaîne du modèle est muse-video-1.0/text-to-video. Traitez-la comme un littéral sensible à la casse. Ne composez pas et ne devinez pas de variantes, comme une casse différente ou un suffixe manquant — un identifiant de modèle inconnu entraîne une erreur de validation, pas un repli.

Une fois ces trois éléments prêts, vous pouvez construire le corps de la requête.

La requête curl fonctionnelle

Le corps de la requête est du JSON. Sur le plan conceptuel, il contient trois groupes de champs.

Le prompt

Le prompt est l'instruction créative ; il détermine la majeure partie de la qualité de la sortie. Un prompt efficace décrit concrètement le sujet, l'action, le comportement de la caméra, l'éclairage et le style, plutôt que d'empiler des adjectifs. Il s'agit d'un simple champ de type chaîne.

La durée

Le modèle text-to-video doit savoir quelle longueur doit avoir le clip. La durée est un champ de la requête et influence aussi le coût : la génération est facturée à la seconde de sortie. Comme la plage acceptée et la valeur par défaut sont définies par le modèle à un instant donné, lisez le nom exact du champ et les valeurs autorisées dans la référence API en direct de muse-video-1.0/text-to-video, sans deviner. Transmettre une durée hors plage provoque un échec de validation.

L'audio

muse-video-1.0/text-to-video prend en charge, en plus de la génération visuelle, des contrôles liés à l'audio. Ce sont également des champs de la requête — généralement des interrupteurs ou des entrées de type prompt audio — dont les noms exacts et les valeurs acceptées sont documentés dans la même référence API. Pour une première intégration, l'approche prudente consiste à omettre entièrement les champs audio optionnels, à confirmer que la vidéo est bien renvoyée, puis à ajouter les options audio une par une.

Le corps de requête minimal ressemble donc à peu près à ceci (les noms de champs ne sont donnés qu'à titre d'exemple — vérifiez-les dans la référence) :

{
  "model": "muse-video-1.0/text-to-video",
  "prompt": "Au lever du soleil, un lent travelling aérien avance au-dessus d'une forêt de pins brumeuse, lumière volumétrique douce, rendu cinématographique",
  "duration": 5
}

Comme le jeu de paramètres est susceptible d'évoluer, l'habitude fiable est la suivante : récupérez la documentation de référence du modèle, copiez les noms de champs à l'identique et validez localement avant d'envoyer.

La même requête en Python

L'appel de soumission n'est qu'un POST HTTP. Le chemin de ressource exact est défini par la référence API HiAPI ; l'exemple ci-dessous utilise le point de terminaison de tâche habituel, le modèle étant placé dans le corps de la requête.

curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video-1.0/text-to-video",
    "prompt": "Un robot en carton traverse une ruelle néon sous la pluie, reflets sur l'asphalte mouillé, rendu pellicule 35 mm",
    "duration": 5
  }'

La réponse est courte et revient vite. Ce qui compte, c'est l'identifiant de tâche et l'état. La structure typique est la suivante :

{
  "id": "job_abc123",
  "status": "queued"
}

Notez l'id — c'est le handle de tous vos appels suivants. Un status à queued ou processing est normal : cela signifie que la requête a été acceptée, et non qu'un problème est survenu.

Interrogation manuelle dans le shell :

curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Exécutez-la plusieurs fois à intervalles réguliers et observez l'évolution de status vers l'état terminal. En pratique, cette boucle doit vivre dans le code, et non dans l'historique du terminal.

Gérer les résultats asynchrones et interroger sans marteler l'API

La version Python fait les deux mêmes choses — soumettre, puis interroger — mais ajoute la gestion des délais, des nouvelles tentatives bornées et la sauvegarde du résultat, pour pouvoir s'exécuter sans surveillance en toute sécurité.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}

MODEL = "muse-video-1.0/text-to-video"

def submit(prompt: str, duration: int) -> str:
    resp = requests.post(
        f"{BASE}/v1/video/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"model": MODEL, "prompt": prompt, "duration": duration},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def wait_for(job_id: str, max_wait: int = 900) -> dict:
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/video/generations/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        if r.status_code >= 500 or r.status_code == 429:
            time.sleep(interval)
            interval = min(interval * 2, 30)
            continue
        r.raise_for_status()
        job = r.json()
        if job["status"] == "succeeded":
            return job
        if job["status"] == "failed":
            raise RuntimeError(job.get("error") or "generation failed")
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in time")

def save(job: dict, path: str) -> None:
    url = job["result"]["video_url"]
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(8192):
                f.write(chunk)

if __name__ == "__main__":
    job_id = submit(
        "Un petit écosystème en verre posé sur une table en bois, lumière du matin, particules de poussière en suspension, macro",
        5,
    )
    job = wait_for(job_id)
    save(job, "output.mp4")
    print("saved output.mp4")

Trois choix réfléchis ici. Les nouvelles tentatives sont bornées par une échéance plutôt que par un nombre d'itérations, donc elles ne suspendront pas indéfiniment. Le backoff augmente lors d'échecs transitoires et croît lentement lors de l'interrogation du chemin de succès. Le téléchargement est une requête streaming séparée, ce qui évite de faire passer un gros fichier par le chemin JSON.

Erreurs courantes et méthodes de diagnostic

La fréquence d'interrogation est une véritable décision de conception. Interroger toutes les 200 ms ne génère qu'une charge inutile ; interroger toutes les cinq minutes fait perdre du temps réel une fois le rendu terminé.

Stratégie pratique :

  • Démarrez avec un intervalle modéré (quelques secondes) et augmentez-le progressivement — multiplier par 1,5 à chaque interrogation, avec un plafond d'environ une demi-minute, fonctionne bien.
  • Augmentez le backoff pour les réponses 429 et 5xx : doublez l'intervalle et réessayez, en les traitant comme un signal de capacité plutôt que comme un état de tâche.
  • Définissez un temps d'attente total maximal et levez une erreur en cas de dépassement, plutôt que d'interroger indéfiniment. Les rendus de durée plus longue prennent effectivement plus de temps, donc le plafond doit être fixé selon votre propre charge de travail.
  • Ne consignez une transition qu'une seule fois, lors du changement d'état, et non à chaque interrogation — des journaux bruyants rendent les vraies défaillances difficiles à repérer.

La réponse d'une tâche terminée contient généralement le status terminal, l'id de la tâche et une charge de résultat comprenant l'URL de la vidéo téléchargeable, parfois accompagnée de métadonnées et d'une date d'expiration de l'URL. Récupérez le fichier rapidement après le succès. Si la tâche signale failed, lisez le message d'erreur de la réponse avant de réessayer — un échec de validation ne réussira jamais en réessayant, tandis qu'une erreur de rendu interne le peut.

Étapes suivantes

Commencez par le corps de requête minimal, confirmez une exécution de bout en bout réussie, puis ajoutez les contrôles de durée et d'audio en vous appuyant sur la documentation de référence actuelle de muse-video-1.0/text-to-video. Le même modèle « soumettre puis interroger » se transpose aux autres points de terminaison de modèles HiAPI, donc le code client que vous écrivez ici est réutilisable.

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