Skip to main content

Référence de l'API d'édition vidéo HappyHorse

Le modèle d'édition vidéo HappyHorse prend en entrée une vidéo et une image de référence, puis exécute des tâches d'édition telles que le transfert de style ou le remplacement local, conformément aux instructions textuelles fournies.

Disponibilité

Assurez-vous que le modèle, l'URL de l'endpoint et la clé API appartiennent tous à la même région. Les appels interrégionaux échouent systématiquement.
  • Sélectionner un modèle : Vérifiez la région du modèle.
  • Choisir une URL : Utilisez l'URL de l'endpoint correspondant à votre région. Les URL HTTP sont prises en charge.
  • Configurer une clé API : Sélectionnez une région, créez une clé API, puis exportez-la en tant que 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 aux espaces de travail pour les régions Chine (Pékin) et Singapour. Ces 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 ces 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 dans la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.

Requête HTTP

Les tâches d'édition vidéo nécessitant un temps de traitement important (généralement 1 à 5 minutes), l'API fonctionne par appels asynchrones. Le flux de travail se déroule en deux étapes : « Créer une tâche -> Interroger le résultat », comme décrit ci-dessous :

Étape 1 : Créer une tâche et obtenir son ID

  • 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 périodique pour récupérer le résultat.
  • Pour un guide destiné aux débutants, consultez Appeler des API avec Postman ou cURL.

Paramètres de la requête

  • Édition vidéo (instruction + image de référence)
# 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.0-video-edit",
    "input": {
        "prompt": "Make the horse-headed humanoid character in the video wear the striped sweater from the image",
        "media": [
            {
                "type": "video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"
            }
        ]
    },
    "parameters": {
        "resolution": "720P"
    }
}'
En-têtes
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.Valeur fixe : happyhorse-1.0-video-edit.
input object (Obligatoire)Informations d'entrée comprenant la vidéo à éditer, les images de référence et l'instruction textuelle.

Propriétés

prompt string (Obligatoire)Instruction textuelle décrivant la modification souhaitée, telle qu'un transfert de style ou un remplacement local.Toutes les langues sont prises en charge. Limite de 5 000 caractères non chinois ou 2 500 caractères chinois. Le contenu excédentaire est automatiquement tronqué.media array (Obligatoire)Liste des ressources multimédias, incluant la vidéo à éditer et d'éventuelles images de référence.Ce tableau doit contenir exactement 1 élément video et peut optionnellement inclure entre 0 et 5 éléments reference_image.

Propriétés des éléments

type string (Obligatoire)Type de ressource multimédia. Doit correspondre à l'une des valeurs suivantes :
  • video : Obligatoire. Vidéo à éditer.
  • reference_image : Facultatif. Image de référence.
Limites applicables aux ressources :
  • Vidéos : exactement 1.
  • Images de référence : de 0 à 5.
url string (Obligatoire)URL de la ressource multimédia.

Entrée vidéo (type=video)

URL publiquement accessible de la vidéo à éditer.Exigences relatives à la vidéo :
  • Format : MP4, MOV (encodage H.264 recommandé).
  • Durée : de 3 à 60 secondes.
  • Résolution : le côté le plus long ne doit pas dépasser 4 096 px ; le côté le plus court doit mesurer au moins 360 px.
  • Rapport d'aspect : de 1:2,5 à 2,5:1.
  • Taille du fichier : jusqu'à 100 Mo.
  • Fréquence d'images : supérieure à 8 ips.
Durée de la vidéo générée : de 3 à 15 secondes.
  • Si la vidéo d'entrée dure 15 secondes ou moins, la vidéo générée conserve cette même durée.
  • Si la vidéo d'entrée dépasse 15 secondes, le système n'utilise automatiquement que les 15 premières secondes ; la durée maximale de sortie est donc limitée à 15 secondes.

Entrée image (type=reference_image)

URL ou données encodées en Base64 de l'image de référence.Exigences relatives à l'image :
  • Formats acceptés : JPEG, JPG, PNG, WEBP.
  • Résolution : la largeur et la hauteur doivent toutes deux être d'au moins 300 px.
  • Rapport d'aspect : de 1:2,5 à 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é à titre d'illustration).

      Format des données 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 d'édition vidéo tels que la résolution.

Propriétés

resolution string (Facultatif)Résolution de la vidéo générée.Valeurs valides :
  • 1080P (par défaut)
  • 720P
watermark boolean (Facultatif)Indique si un filigrane doit être ajouté à la vidéo générée. Celui-ci apparaît dans le coin inférieur droit avec le texte « Happy Horse ». La valeur par défaut est true.
  • true (par défaut)
  • false
audio_setting string (Facultatif)Contrôle audio.
  • auto (par défaut) : Déterminé par le modèle.
  • origin : Conserve la piste audio originale de la vidéo d'entrée.
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. L'utilisation d'une graine fixe améliore la reproductibilité des résultats.La génération du modèle étant probabiliste, une 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 objectInformations de sortie 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 les résultats via l'ID de 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}
  • Interrogation périodique : L'édition vidéo prenant plusieurs minutes, mettez en place un mécanisme d'interrogation à intervalles réguliers (par exemple, toutes les 15 secondes) pour vérifier la disponibilité des résultats.
  • Cycle de vie de la tâche : PENDING (en file d'attente) → RUNNING (en cours de traitement) → SUCCEEDED / FAILED.
  • Expiration du task_id : L'identifiant de tâche expire au bout de 24 heures. Passé ce délai, les résultats ne sont plus récupérables et l'API retourne un état de tâche UNKNOWN.

Paramètres de la requête

  • Interroger le résultat d'une tâche
Remplacez {task_id} par la valeur task_id retournée lors de l'appel API précédent. Ce 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
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
  • Requête de tâche expirée
Les URL vidéo ne sont valides que pendant 24 heures avant d'être automatiquement supprimées. Pensez à sauvegarder rapidement vos vidéos générées.
{
    "request_id": "c11018a8-3f83-9591-a636-xxxxxx",
    "output": {
        "task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-26 14:13:14.373",
        "scheduled_time": "2026-04-26 14:13:14.419",
        "end_time": "2026-04-26 14:14:13.679",
        "orig_prompt": "Dress the horse-headed humanoid character in the video in the striped sweater from the image",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 13,24,
        "input_video_duration": 6,62,
        "output_video_duration": 6,62,
        "video_count": 1,
        "SR": 720
    }
}
outputobjectInformations de sortie 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.
  • Lors de la première interrogation, l'état 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 exprimée 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 exprimée 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 exprimée 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. Retournée uniquement lorsque task_status vaut SUCCEEDED.Valide pendant 24 heures. La vidéo est au format MP4 avec un encodage H.264.orig_prompt stringInstruction d'entrée originale, 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. Ne comptabilise que les résultats réussis.

Propriétés

duration floatDurée totale de la vidéo générée, utilisée pour la facturation.SR integerNiveau de résolution de la vidéo générée.output_video_duration floatDurée de la vidéo de sortie, en secondes.input_video_duration floatDurée de la vidéo d'entrée, en secondes.video_count integerNombre de vidéos générées. Toujours égal à 1.
request_id stringIdentifiant unique de la requête, utilisé pour le suivi et le dépannage.

Codes d'erreur

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