Tutoriel
Tutoriel API muse-video-1.0 image-to-video : curl et Python Requests
Sur cette page
Ce que le point de terminaison image-to-video de muse-video-1.0 exige
Le point de terminaison muse-video-1.0/image-to-video transforme une seule image statique en une courte vidéo. Avant d'écrire la première ligne de code, comprendre la structure de la requête vous aide à assembler correctement la charge utile du premier coup.
À haut niveau, un appel implique quatre aspects :
- Routage du modèle — vous spécifiez le modèle via l'API unifiée HiAPI avec
muse-video-1.0/image-to-video. - Image d'entrée — la frame statique qui sert de point de départ à l'animation. C'est l'entrée créative requise.
- Options de génération — le comportement audio et le palier de durée, qui façonnent les caractéristiques de la sortie plutôt que le matériel source.
- Exécution asynchrone — la génération ne renvoie pas la vidéo finale de manière inline. Vous soumettez d'abord une tâche, puis vous interrogez le résultat.
Ce dernier point est le plus souvent négligé par les développeurs. Comme le rendu prend du temps, le point de terminaison repose sur un mécanisme de tâche : l'appel initial confirme votre requête et renvoie un identifiant, puis vous suivez l'état jusqu'à ce que la vidéo soit prête. Concevez votre client autour de ce flux en deux phases dès le départ, plutôt que d'ajouter l'interrogation après coup.
Le corps de la requête est du JSON. Les champs sont structurés en groupes : l'image se trouve dans un bloc input distinct, tandis que l'audio et la durée sont à côté, en tant que paramètres de génération. Gardez ce modèle mental — entrée, options et cycle de vie de la tâche séparés — et le reste de ce tutoriel sera direct.
Authentification
Chaque requête est authentifiée avec votre clé API HiAPI, sous forme d'identifiant bearer dans l'en-tête Authorization. Traitez la clé comme un secret : chargez-la depuis une variable d'environnement plutôt que de la coder en dur dans un script que vous pourriez partager.
export HIAPI_API_KEY="your_api_key_here"
Une fois la clé exportée, vous avez tout le nécessaire pour comprendre la requête. Les sections suivantes construisent la charge utile étape par étape.
Préparer et téléverser votre image de première frame
L'image de première frame est l'ancre créative de toute la tâche. Ce que vous fournissez devient la frame zéro, à partir de laquelle le modèle anime la suite. Bien la préparer évite de gaspiller des générations.
Conseils pratiques pour la frame source
- Utilisez une image statique nette et de haute qualité. Ce qui se lit bien comme image unique offre au modèle le meilleur point de départ.
- Choisissez un rapport d'aspect correspondant à la sortie visée. Une image panoramique large et une image verticale longue produisent des compositions très différentes ; déterminez donc l'orientation avant le téléversement réel.
- Évitez le flou de mouvement prononcé ou un sujet ambigu. Une image statique déjà visuellement stable génère une animation plus prévisible.
- Assurez-vous que le fichier est accessible au moment de la requête. Que vous passiez une URL ou une charge utile encodée, vérifiez que la référence est joignable au moment de la soumission de la tâche.
Comment l'image entre dans la requête
L'image est fournie dans le bloc input du corps JSON. Une entrée d'image minimale ressemble à ceci :
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
}
}
Si votre image source est stockée localement, hébergez-la à un emplacement accessible par la requête, ou transmettez-la sous la forme encodée acceptée par le point de terminaison. La règle clé : la valeur dans input.image doit se résoudre en un contenu d'image réel au moment de la création de la tâche — un lien cassé ou expiré échouera à la soumission, et non à l'interrogation, ce qui est en fait un signal précoce utile.
Vérifier avant de générer
Une vérification rapide de bon sens vaut la peine : ouvrez l'URL de l'image dans un navigateur, confirmez qu'elle se charge, puis confirmez que les dimensions conviennent à votre sortie prévue. Deux secondes de vérification ici évitent un débogage déroutant plus tard.
Une fois la première frame prête et accessible, vous pouvez passer aux options de génération.
Configurer les paramètres audio et les paliers de durée
Outre l'image, muse-video-1.0/image-to-video propose deux catégories d'options qui modifient les caractéristiques de la sortie : le comportement audio et la durée.
Paramètre audio
L'audio est représenté par un champ dans le corps de la requête, à côté de votre input. Déterminez l'intention avant l'appel :
- Sortie silencieuse — gardez l'audio désactivé si vous prévoyez d'ajouter votre propre bande son en post-production ou si vous avez besoin d'une piste vidéo propre.
- Audio activé — activez l'audio si le clip doit avoir son propre son. Vérifiez explicitement cette option dans la charge utile plutôt que de supposer une valeur par défaut.
Comme le traitement audio est une propriété de la requête elle-même, et non une étape de post-traitement, il vaut la peine de le fixer avant de passer à l'échelle. Si votre pipeline mélange des clips silencieux et des clips avec audio, modélisez ce choix comme un paramètre explicite dans votre propre code client, pour éviter tout accident.
Paliers de durée
Le point de terminaison vous permet de choisir un palier de durée pour le clip. Traitez la durée comme une décision créative et de coût délibérée :
- Paliers courts adaptés aux aperçus rapides, aux clips sociaux et aux tests de storyboard, lorsque vous voulez un retour rapide sur de nombreuses images sources.
- Paliers longs offrent plus d'espace à l'animation, mieux adaptés aux plans principaux ou aux séquences qui ont besoin de respirer.
La durée est facturée en secondes de sortie, le palier choisi impacte donc directement la consommation. Il n'y a aucun avantage à rendre un long clip juste pour une vérification visuelle rapide — utilisez les paliers courts pendant l'itération sur la première frame, puis promouvez les réglages gagnants vers un palier plus long.
Assembler ces options ensemble
En JSON, les paramètres audio et de durée sont à côté du bloc input :
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}
Utilisez les identifiants de palier exacts indiqués dans la documentation du point de terminaison, plutôt que de deviner des valeurs. La section suivante en fait une requête exécutable.
Une requête curl fonctionnelle
Une fois la charge utile assemblée, voici la commande curl pour la soumission initiale. Elle crée la tâche ; elle ne renvoie pas la vidéo finale.
curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}'
Quelques remarques sur cette commande :
- L'URL spécifie le modèle par son nom. Vous n'avez pas besoin d'un client distinct par modèle ; le chemin identifie déjà
muse-video-1.0/image-to-video. - L'en-tête porte votre clé.
$HIAPI_API_KEYest développé depuis la variable d'environnement que vous avez exportée précédemment, la clé n'apparaît donc jamais dans le script lui-même. - Le corps est la charge utile que vous venez de construire. L'URL de l'image, l'indicateur audio et le palier de durée sont transmis ensemble.
La réponse est une confirmation de tâche : elle contient l'identifiant de la tâche que vous venez de créer. Copiez cet identifiant — il sera utilisé à l'étape d'interrogation. Si vous ne faites qu'explorer, vous pouvez formater la réponse avec un outil JSON pour trouver plus facilement l'ID de tâche.
Si la soumission échoue, l'erreur est généralement immédiate et spécifique : corps JSON mal formé, référence d'image manquante, ou valeur d'option non reconnue. Cette boucle de retour rapide justifie de tester la soumission séparément avant d'ajouter l'interrogation.
La même requête en Python
La plupart des intégrations finissent en Python, voici donc la soumission équivalente utilisant la bibliothèque standard — sans SDK tiers.
import json
import os
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"
payload = {
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": True,
"duration": "<duration_tier>",
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
result = json.loads(response.read().decode("utf-8"))
job_id = result["id"]
print("Submitted job:", job_id)
Ce script correspond champ par champ à l'appel curl. Quelques habitudes à adopter :
- Conservez la charge utile dans un dictionnaire. La construire comme un dictionnaire Python signifie que vous pouvez l'utiliser avec n'importe quelle bibliothèque HTTP —
urllib,requestsou un client asynchrone — sans réécrire la logique. - Lisez la clé depuis l'environnement.
os.environgarde les identifiants hors du contrôle de source. - Analysez immédiatement la réponse en JSON. Extraire l'ID de tâche dans une variable nommée rend l'étape d'interrogation plus lisible.
Si vous préférez la bibliothèque requests, le seul changement est la couche de transport : construisez le même dictionnaire payload et envoyez-le avec votre ensemble d'en-têtes, puis appelez .json() sur la réponse. Le point de terminaison, les en-têtes et le corps restent identiques.
Une fois la tâche soumise et son identifiant capturé, il ne reste plus qu'à attendre le résultat de la bonne manière.
Interroger la tâche asynchrone et récupérer la vidéo
La génération vidéo n'est pas instantanée, le point de terminaison est donc asynchrone. Après la soumission, vous interrogez l'état de la tâche pour savoir quand le rendu est terminé, puis vous récupérez la sortie.
Boucle d'interrogation
Une boucle robuste fait trois choses : attendre entre les vérifications, fixer une limite pour ne pas tourner indéfiniment, et distinguer « toujours en cours », « terminé » et « échec ».
import time
import urllib.request
STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"
def wait_for_video(job_id, max_attempts=60, interval=5):
for attempt in range(max_attempts):
url = STATUS_ENDPOINT.format(job_id=job_id)
request = urllib.request.Request(
url,
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(request) as response:
status = json.loads(response.read().decode("utf-8"))
state = status.get("status")
if state == "succeeded":
return status.get("output")
if state == "failed":
raise RuntimeError(f"Job {job_id} failed: {status}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} did not finish in time")
Points de conception pour la production
- Utilisez un intervalle raisonnable. Cinq secondes est un bon point de départ ; ne bombardez pas le point de terminaison d'état.
- Limitez toujours le nombre de tentatives. La limite
max_attemptstransforme une attente infinie en une erreur claire que vous pouvez journaliser et alerter. - Gérez explicitement les états d'échec. Une tâche échouée contient des informations de diagnostic — exposez-les au lieu de réessayer silencieusement avec la même entrée.
- Persistez l'ID de tâche. Si votre processus redémarre, vous pouvez reprendre l'interrogation sans payer une nouvelle génération.
Récupérer la sortie
Lorsque la tâche réussit, la réponse d'état contient une référence de sortie vers la vidéo finale. Téléchargez-la en temps utile dans votre propre stockage, plutôt que de dépendre d'un lien à longue durée. Une fois que vous détenez le fichier en local ou dans un bucket, du point de vue du pipeline la génération est terminée.
C'est tout le cycle de vie : soumettre, interroger, récupérer. Séparez les deux phases dans le code, et chacune restera simple.
Pièges courants et astuces de débogage
La plupart des problèmes d'intégration avec muse-video-1.0/image-to-video se rangent dans quelques catégories. Voici quoi vérifier lorsque quelque chose ne va pas.
Problèmes d'entrée d'image
- Référence d'image injoignable. Si l'URL nécessite une authentification ou a expiré, la tâche échoue à la soumission. Hébergez la frame à un emplacement lisible publiquement pendant la requête.
- Incompatibilité de rapport d'aspect. Forcer une image statique verticale dans une sortie horizontale provoque un recadrage gênant ou des bandes noires. Définissez l'orientation de la source pour correspondre à la cible.
- Mauvais contenu. Il est facile de pointer vers une vignette ou une image de remplacement plutôt que vers la vraie frame. Vérifiez que l'URL ouvre bien l'image attendue.
Erreurs de paramètres
- Deviner les valeurs de durée. Utilisez les identifiants de palier exacts indiqués dans la documentation du point de terminaison. Les valeurs non reconnues sont une cause courante de rejet.
- Oublier l'indicateur audio. Si vous omettez le paramètre audio tout en attendant du son, vous risquez d'obtenir un clip silencieux. Soyez explicite sur le besoin d'audio.
- Confondre champs de premier niveau et champs input. L'image va à l'intérieur de
input; l'audio et la durée sont des frères deinput, pas ses enfants. Une mauvaise imbrication produit des messages de validation déroutants.
Erreurs d'interrogation
- Prendre la soumission pour l'achèvement. La première réponse n'est qu'une confirmation, pas la vidéo. Suivez toujours avec une vérification d'état.
- Interrogation sans limite. Une boucle sans plafond bloquera votre worker si la tâche stagne. Ajoutez une limite et une erreur de délai d'attente.
- Ignorer les échecs. Une tâche qui se termine en état d'échec ne produira jamais de vidéo ; capturez-la et examinez les diagnostics au lieu de continuer d'attendre.
- Attendre longtemps sur une mauvaise entrée. Lorsque le rendu échoue de manière répétée, arrêtez de régénérer. Corrigez d'abord la frame source ou les paramètres, puis soumettez de nouveau.
Un ordre de débogage efficace
- Confirmez que l'URL de l'image se charge dans un navigateur.
- Soumettez une charge utile minimale avec seulement l'image, pour isoler les problèmes de paramètres.
- Vérifiez que l'ID de tâche est renvoyé proprement.
- Interrogez d'abord manuellement pour observer les transitions d'état.
- Seulement après cela, automatisez la boucle et ajoutez des réessais pour les erreurs réseau transitoires.
Traiter ces étapes dans l'ordre permet de réduire rapidement le problème à une couche — image, options ou cycle de vie — et de maintenir l'intégration en progression. Après avoir compris la structure de la requête, les options et le flux d'interrogation, vous êtes prêt à construire sur ce point de terminaison.
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