Skip to main content

HappyHorse - référence vers vidéo, référence de l'API

Le modèle HappyHorse référence vers vidéo vous permet de fournir plusieurs images de référence et une invite textuelle pour générer une vidéo combinant les sujets des images dans une scène basée sur l'invite.

Notes d'utilisation

Pour garantir le succès des appels API, utilisez un modèle, une URL d'endpoint et une clé API appartenant tous à la même région. Les appels interrégions échouent.
  • Sélectionnez un modèle : Confirmez la région où se trouve votre modèle.
  • Sélectionnez une URL : Choisissez l'URL d'endpoint correspondante. Les URLs HTTP et SDK DashScope sont prises en charge.
  • Configurez une clé API : Sélectionnez une région, obtenez une clé API, puis configurez la clé API en tant que variable d'environnement.
L'exemple de code de cette rubrique s'applique à la région Singapour.
Alibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions Chine (Pékin) et Singapour. Les nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers les nouveaux domaines :
  • Chine (Pékin) : de https://dashscope.aliyuncs.com vers https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : de https://dashscope-intl.aliyuncs.com vers 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 entièrement fonctionnel.

Appels HTTP

Étant donné que les tâches de référence vers vidéo sont chronophages (généralement 1 à 5 minutes), l'API utilise un appel asynchrone. Le flux de travail comprend deux étapes principales : « Créer une tâche -> Interroger le 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 ID d'espace de travail réel.
  • Une fois la tâche créée, utilisez le task_id renvoyé pour interroger le résultat. Le task_id est valide pendant 24 heures. Ne créez pas de tâches dupliquées. Utilisez plutôt le mécanisme d'interrogation pour récupérer le résultat.
  • Pour obtenir des conseils destinés aux débutants, consultez la rubrique Appeler des API avec Postman ou cURL.

Paramètres de requête

  • Référence vers vidéo (multi-images)
# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual 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-r2v",
        "input": {
            "prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the tailored cut and S-curve of the dress. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
            "media": [
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
                },
                {
                    "type": "reference_image",
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
                }
            ]
        },
        "parameters": {
            "resolution": "720P",
            "ratio": "16:9",
            "duration": 5
        }
    }'
En-têtes de requête
Content-Type string (Obligatoire)Type de contenu de la requête. Doit être application/json.
Authorization string (Obligatoire)Authentifie la requête avec 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. Doit être enable.
Si cet en-tête de requête est manquant, l'erreur « current user api does not support synchronous calls » est renvoyée.
Corps de la requête
model string (Obligatoire)Nom du modèle. Pour connaître les modèles disponibles, consultez la console Model Studio.Exemple : happyhorse-1,1-r2v.
input object (Obligatoire)Entrée du modèle, comprenant les images de référence et l'invite textuelle.

Propriétés

prompt string (Obligatoire)Description des éléments souhaités et du style visuel pour la vidéo générée.La saisie dans n'importe quelle langue est prise en charge. La longueur est limitée à 5 000 caractères non chinois ou 2 500 caractères chinois. Le contenu dépassant cette limite est automatiquement tronqué.Référencement d'image : Dans l'invite, utilisez « [Image 1] » et « [Image 2] » pour faire référence à l'image de référence correspondante dans le tableau media. L'ordre doit être cohérent avec celui du tableau media. Lors de l'utilisation d'une référence, spécifiez l'objet dans l'image, par exemple « la femme en qipao rouge dans [Image 1] ».media array (Obligatoire)Liste des images de référence.Chaque élément du tableau est un objet média contenant les champs type et url.
  • L'ordre des éléments dans ce tableau définit l'ordre des références de sujet dans l'invite.
  • La première reference_image du tableau correspond à [Image 1], la seconde à [Image 2], et ainsi de suite.

Propriétés des éléments

type string (Obligatoire)Type de ressource multimédia. Définissez cette valeur sur :
  • reference_image : Une image de référence.
Limites des ressources :
  • Nombre d'images de référence : 1 à 9.
url string (Obligatoire)URL ou données encodées en Base64 d'une image de référence.Exigences relatives aux images :
  • Formats : JPEG, JPG, PNG, WEBP.
  • Résolution : Le côté le plus court doit mesurer au moins 400 pixels. Une image nette d'une résolution de 720P ou supérieure est recommandée. Évitez d'utiliser des images trop petites, floues ou excessivement compressées, car cela peut dégrader la qualité de sortie.
  • Taille maximale du fichier : 20 Mo.
Formats d'entrée pris en charge :
  1. URL publique :
  2. Chaîne d'image encodée en Base64 :
    • Format des données : data:{MIME_type};base64,{base64_data}.
    • Exemple : data:image/png;base64,GDU7MtCZzEbTbmRZ...... (tronqué pour l'affichage).

      Format des données encodées en Base64

      Format : data:{MIME_type};base64,{base64_data} .
      • {base64_data} : Chaîne 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 génération de vidéo, tels que la résolution vidéo, le rapport d'aspect et la durée.

Propriétés

resolution string (Facultatif)Niveau de résolution de la vidéo générée.Valeurs valides :
  • 480P
  • 720P
  • 1080P : Valeur par défaut.
ratio string (Facultatif)Rapport d'aspect de la vidéo générée.Valeurs valides :
  • 16:9 : Valeur par défaut.
  • 9:16
  • 3:4
  • 4:3
  • 4:5
  • 5:4
  • 1:1
  • 9:21
  • 21:9
duration integer (Facultatif)Durée de la vidéo générée, en secondes.Plage de valeurs : Un entier compris entre 3 et 15.Valeur par défaut : 5.watermark boolean (Facultatif)Indique s'il faut ajouter un filigrane à la vidéo générée. Le filigrane est placé dans le coin inférieur droit avec le texte fixe « Happy Horse ».
  • true : Valeur par défaut. Un filigrane est ajouté.
  • false : Aucun filigrane n'est ajouté.
seed integer (Facultatif)La graine aléatoire doit être un entier compris dans la plage [0, 2147483647].Si elle n'est pas spécifiée, une graine aléatoire est générée. Une graine fixe améliore la reproductibilité.Étant donné que la génération du modèle est probabiliste, la même graine ne garantit pas des résultats identiques.

Paramètres de réponse

  • Réponse réussie
  • Réponse d'erreur
Enregistrez le task_id pour interroger 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 objectInformations de sortie de la tâche.

Propriétés

task_id stringID de la tâche. Valide pour les interrogations pendant 24 heures.task_status stringÉtat 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 pour le suivi et le dépannage.
code stringCode d'erreur. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.
message stringMessage d'erreur détaillé. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.

Étape 2 : Obtenir le résultat de la tâche

  • 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 de vidéo peut prendre plusieurs minutes. Nous vous recommandons de mettre en œuvre un mécanisme d'interrogation avec un intervalle de requête raisonnable (par exemple, 15 secondes) pour récupérer le résultat.
  • Flux d'état de la tâche : PENDING (En file d'attente) → RUNNING (En cours de traitement) → SUCCEEDED (Réussie) ou FAILED (Échouée).
  • Validité de l'ID de tâche : L'ID de tâche est valide pendant 24 heures. Passé ce délai, vous ne pouvez plus interroger le résultat et l'API renvoie un état de tâche UNKNOWN.

Paramètres de requête

  • Interroger le résultat de la tâche
Remplacez {task_id} par la valeur task_id renvoyée par l'appel API précédent. Le task_id est valide pour les interrogations pendant 24 heures, Remplacez {WorkspaceId} par votre ID d'espace de travail réel.
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 avec une clé API Model Studio. Exemple : Bearer sk-xxxx.
Paramètres de chemin d'URL
task_id string (Obligatoire)ID de la tâche.

Paramètres de réponse

  • Tâche réussie
  • Échec de la tâche
  • Expiration de l'interrogation de la tâche
Les URL de vidéo ne sont valides que pendant 24 heures, puis sont automatiquement purgées. Enregistrez rapidement les vidéos générées.
{
        "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
        "output": {
            "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
            "task_status": "SUCCEEDED",
            "submit_time": "2026-04-25 15:03:25.848",
            "scheduled_time": "2026-04-25 15:03:25.884",
            "end_time": "2026-04-25 15:04:05.882",
            "orig_prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the dress'\''s tailored cut and S-curve. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
            "video_url": "https://dashscope-result-intl.oss-ap-southeast-1.aliyuncs.com/xxxx.mp4"
        },
        "usage": {
            "duration": 5,
            "input_video_duration": 0,
            "output_video_duration": 5,
            "video_count": 1,
            "SR": 720,
            "ratio": "16:9"
        }
    }
outputobjectInformations de sortie de la tâche.

Propriétés

task_id stringID de la tâche. Valide pour les interrogations pendant 24 heures.task_status stringÉtat 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 de la requête initiale 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, vérifiez le message d'erreur et réessayez la tâche.
submit_time stringHeure de soumission de la tâche. L'heure est en 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 en 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 en UTC+8 et le format est AAAA-MM-JJ HH:mm:ss.SSS.video_url stringURL de la vidéo générée. Renvoyée uniquement lorsque task_status est SUCCEEDED.Valide pendant 24 heures. La vidéo est au format MP4 avec encodage H.264.orig_prompt stringInvite d'entrée d'origine, correspondant au paramètre de requête prompt.code stringCode d'erreur. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.message stringMessage d'erreur détaillé. Renvoyé uniquement pour les requêtes ayant échoué. Consultez les Codes d'erreur.
usage objectStatistiques d'utilisation de la tâche. Vous êtes facturé uniquement pour les tâches réussies.

Propriétés

duration integerDurée facturable de la vidéo générée, en secondes.input_video_duration integerDurée totale de la vidéo d'entrée, en secondes. Cette valeur est toujours 0 pour les tâches de référence vers vidéo.output_video_duration integerDurée totale de la vidéo de sortie, en secondes.ratio stringRapport d'aspect de la vidéo générée.SR integerNiveau de résolution de la vidéo générée.video_count integerNombre de vidéos générées. Cette valeur est toujours 1.
request_id stringIdentifiant unique de la requête pour le suivi et le dépannage.

Codes d'erreur

Si l'appel au modèle échoue et renvoie un message d'erreur, consultez les Codes d'erreur pour résoudre le problème.