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
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 :
- 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.
- 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
429et5xx: 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 →-
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