Skip to main content

Référence de l'API image-vers-vidéo (première frame) HappyHorse

Générez des vidéos réalistes aux mouvements fluides à partir d'une image de première frame et d'un prompt textuel facultatif grâce au modèle HappyHorse.

Notes d'utilisation

Le modèle, l'URL de l'endpoint et la clé API doivent appartenir à la même région. Les appels interrégionaux échouent systématiquement.
  • Sélectionnez un modèle : Vérifiez la région associée au modèle.
  • Choisissez une URL : Sélectionnez l'URL de l'endpoint correspondant à cette même région.
  • Configurez une clé API : Obtenez une clé API pour la région concernée, puis configurez-la comme variable d'environnement.
Les exemples de code de cette rubrique s'appliquent à la région Singapour.
Alibaba Cloud Model Studio a publié des domaines spécifiques par espace de travail pour les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés offrent de meilleures performances et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : passez de https://dashscope.aliyuncs.com à https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : passez de https://dashscope-intl.aliyuncs.com à https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} correspond à votre ID d'espace de travail, disponible sur la page Workspace Details de la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.

Appels HTTP

Les tâches image-vers-vidéo nécessitent entre 1 et 5 minutes. L'API fonctionne de manière asynchrone selon le principe « Création de tâche → interrogation du résultat ».

Étape 1 : Créer une tâche

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • Germany (Frankfurt)
  • Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
  • Une fois la tâche créée, utilisez le task_id retourné pour interroger le résultat. Ce task_id reste valide pendant 24 heures. Ne créez pas de tâches en double. Privilégiez plutôt l'interrogation régulière pour obtenir le résultat.
  • Pour un guide destiné aux débutants, consultez Appeler des API avec Postman ou cURL.

Paramètres de la requête

  • Image-vers-vidéo
# The following URLs are for the Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
    curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
        -H 'X-DashScope-Async: enable' \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
        "model": "happyhorse-1.1-i2v",
        "input": {
            "prompt": "A cat running on the grass",
            "media": [
                {
                    "type": "first_frame",
                    "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
                }
            ]
        },
        "parameters": {
            "resolution": "720P",
            "duration": 5
        }
    }'
Content-Type string (Obligatoire)Type de contenu de la requête. Doit être défini à application/json.
Authorization string (Obligatoire)Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx.
X-DashScope-Async string (Obligatoire)Active le traitement asynchrone. Les requêtes HTTP ne prennent en charge que les appels asynchrones. La valeur doit être enable.
Si cet en-tête de requête est absent, l'erreur « current user api does not support synchronous calls » est retournée.
Corps de la requête
model string (obligatoire)Nom du modèle. Pour consulter les modèles disponibles, reportez-vous à la console Model Studio.Exemple : happyhorse-1.1-i2v.
input object (obligatoire)Entrée du modèle, incluant le prompt textuel.

Propriétés

prompt string (facultatif)Décrit le contenu vidéo à générer.Toutes les langues sont prises en charge. Limite maximale : 5 000 caractères non chinois ou 2 500 caractères chinois. Tout texte dépassant cette limite est tronqué.media array (obligatoire)Tableau des images d'entrée.

Propriétés des éléments media[]

type string (obligatoire)Type de média. Valeur autorisée :
  • first_frame : La première frame.
Exactement une image de première frame est requise.url string (obligatoire)URL du média.

Image d'entrée (type=first_frame)

URL ou données encodées en Base64 de l'image de première frame.Contraintes relatives à l'image :
  • Formats acceptés : JPEG, JPG, PNG, WEBP.
  • Résolution : La largeur et la hauteur doivent toutes deux atteindre au moins 300 pixels.
  • Rapport d'aspect : Compris entre 1:2,5 et 2,5:1.
  • Taille du fichier : Jusqu'à 20 Mo.
Formats d'entrée pris en charge :
  1. URL publique :
  2. Chaîne d'image encodée en Base64 :
    • Format : data:{MIME_type};base64,{base64_data}.
    • Exemple : data:image/png;base64,GDU7MtCZzEbTbmRZ...... (tronqué pour l'affichage).

      Format d'encodage Base64

      Format : data:{MIME_type};base64,{base64_data} .
      • {base64_data} : Chaîne encodée en Base64 du fichier image.
      • {MIME_type} : Type MIME de l'image, qui doit correspondre au format du fichier.

      Format d'image

      Type MIME

      JPEG

      image/jpeg

      JPG

      image/jpeg

      PNG

      image/png

      WEBP

      image/webp

parameters object (facultatif)Paramètres de sortie vidéo tels que la résolution et la durée.

Propriétés

resolution string (facultatif)Résolution de la vidéo générée.Le nombre de pixels en sortie se rapproche du niveau sélectionné tout en préservant le rapport d'aspect de l'image d'entrée.Valeurs autorisées :
  • 480P
  • 720P
  • 1080P (Par défaut)
duration integer (facultatif)Durée de la vidéo générée, exprimée en secondes.La valeur doit être un entier compris dans l'intervalle [3, 15]. Valeur par défaut : 5.watermark boolean (facultatif)Ajoute un filigrane textuel « Happy Horse » dans le coin inférieur droit.
  • true (Par défaut)
  • false
seed integer (Facultatif)La graine aléatoire doit être un entier compris dans l'intervalle [0, 2147483647].Si aucune valeur n'est spécifiée, une graine aléatoire est générée automatiquement. Une graine fixe améliore la reproductibilité des résultats.La génération du modèle étant probabiliste, l'utilisation de la même graine ne garantit pas des résultats strictement identiques.

Paramètres de la réponse

  • Réponse réussie
  • Réponse d'erreur
Conservez le task_id afin d'interroger ultérieurement l'état et le résultat de la tâche.
{
        "output": {
            "task_status": "PENDING",
            "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
        },
        "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
    }
output objectSortie de la tâche.

Propriétés

task_id stringIdentifiant de la tâche. Valide pour les requêtes pendant 24 heures.task_status stringÉtat actuel de la tâche.

Valeurs d'énumération

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN : La tâche n'existe pas ou son état est inconnu.
request_id stringIdentifiant unique de la requête, utilisé pour le suivi et le dépannage.
code stringCode d'erreur. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.
message stringMessage d'erreur détaillé. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.

Étape 2 : Interroger le résultat

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • Germany (Frankfurt)
  • Japan (Tokyo)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Recommandation d'interrogation : La génération vidéo prend plusieurs minutes. Mettez en place un mécanisme d'interrogation avec un intervalle raisonnable, par exemple toutes les 15 secondes.
  • Transition des états de tâche : PENDING → RUNNING → SUCCEEDED ou FAILED.
  • Lien du résultat : Lorsqu'une tâche aboutit, une URL vidéo valide pendant 24 heures est retournée. Téléchargez et conservez la vidéo dans un stockage permanent, tel qu'OSS.
  • Validité du task_id : 24 heures. Passé ce délai, les requêtes retournent l'état UNKNOWN pour la tâche.

Paramètres de la requête

  • Interroger le résultat de la tâche
Remplacez {task_id} par la valeur task_id retournée lors de l'appel API précédent. Le task_id reste valide pour les requêtes pendant 24 heures. Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"
En-têtes de requête
Authorization string (Obligatoire)Authentifie la requête à l'aide d'une clé API Model Studio. Exemple : Bearer sk-xxxx.
Paramètres de chemin
task_id string (Obligatoire)Identifiant de la tâche.

Paramètres de la réponse

  • Tâche réussie
  • Échec de la tâche
  • Expiration de la requête de tâche
Les URL vidéo ne sont valides que pendant 24 heures avant d'être automatiquement supprimées. Pensez à sauvegarder rapidement les vidéos générées.
{
    "request_id": "8ae698ba-df2d-966c-abcf-xxxxxx",
    "output": {
        "task_id": "e56d806f-76f9-4037-aefa-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-20 19:33:50.425",
        "scheduled_time": "2026-04-20 19:33:50.463",
        "end_time": "2026-04-20 19:35:34.216",
        "orig_prompt": "A cat running on the grass",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 5,
        "input_video_duration": 0,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}
outputobjectSortie de la tâche.

Propriétés

task_id stringIdentifiant de la tâche. Valide pour les requêtes pendant 24 heures.task_status stringÉtat actuel de la tâche.

Valeurs d'énumération

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN : La tâche n'existe pas ou son état est inconnu.
Transitions d'état lors de l'interrogation :
  • PENDING → RUNNING → SUCCEEDED ou FAILED.
  • L'état initial retourné est généralement PENDING ou RUNNING.
  • Lorsque l'état passe à SUCCEEDED, la réponse contient l'URL de la vidéo générée.
  • Si l'état est FAILED, examinez le message d'erreur et relancez la tâche.
submit_time stringHeure de soumission de la tâche. L'heure est indiquée au fuseau UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.scheduled_time stringHeure d'exécution de la tâche. L'heure est indiquée au fuseau UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.end_time stringHeure de fin de la tâche. L'heure est indiquée au fuseau UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.video_urlstringRetourné uniquement lorsque task_status vaut SUCCEEDED.Cette URL reste valide pendant 24 heures. Elle permet de télécharger la vidéo MP4 (24 fps, encodage H.264).orig_prompt stringPrompt d'entrée original, correspondant au paramètre de requête prompt.code stringCode d'erreur. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.message stringMessage d'erreur détaillé. Retourné uniquement en cas d'échec de la requête. Consultez la section Codes d'erreur.
usage objectStatistiques d'utilisation. Calculées uniquement pour les tâches réussies.

Propriétés

input_video_duration integerDurée de la vidéo d'entrée, en secondes.output_video_duration integerDurée de la vidéo de sortie, en secondes.duration integerDurée vidéo totale prise en compte pour la facturation.SR integerRésolution de la vidéo de sortie.video_count integerNombre de vidéos générées en sortie. Cette valeur est toujours égale à 1.
request_id stringIdentifiant unique de la requête, utilisé pour le suivi et le dépannage.

Codes d'erreur

En cas d'échec d'un appel, consultez la référence des messages d'erreur.

FAQ

Rapport d'aspect de la vidéo

Le rapport d'aspect en sortie correspond à celui de la première frame. Contrairement au modèle texte-vers-vidéo HappyHorse, le mode image-vers-vidéo ne prend pas en charge le paramètre ratio.