Skip to main content

Référence de l’API vidéo à partir de références Vidu

Le modèle vidéo à partir de références de Vidu utilise une image de référence et un prompt textuel. Il intègre le sujet de l’image à la scène décrite par le prompt pour générer une vidéo fluide.

Remarques sur l’utilisation

Pour que les appels d’API aboutissent, utilisez un modèle, une URL de point de terminaison et une clé API de la même région. Les appels entre régions échouent.
Le code d’exemple de cette rubrique s’applique à la région de Singapour.

Appels HTTP

Les tâches vidéo à partir de références prenant généralement de 1 à 5 minutes, l’API utilise des appels asynchrones. Le processus comprend deux étapes principales : « Créer une tâche -> Interroger périodiquement le résultat ».

Étape 1 : créer une tâche

Région de Singapour: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
  • Après la création de la tâche, utilisez le task_id renvoyé pour consulter le résultat. Le task_id est valable 24 heures. Ne créez pas de tâches en double ; interrogez périodiquement le résultat.
  • Pour débuter, consultez Appeler les API avec Postman ou cURL.

Paramètres de requête

En-têtes de requête
Content-Type string (Obligatoire)Le 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 prennent uniquement en charge les appels asynchrones. Doit être enable.
Si cet en-tête est absent, l’erreur "current user api does not support synchronous calls" est renvoyée.
Corps de la requête
model string (obligatoire)Le modèle à utiliser. Valeurs valides :
  • vidu/viduq3-ad_reference2video
  • vidu/viduq3-drama_reference2video
  • vidu/viduq3-mix_reference2video

Guide de sélection du modèle

  • Vidéos publicitaires: Utilisez viduq3-ad. Conçu pour la publicité, il propose des transitions intelligentes entre plans et des mouvements de caméra adaptés au marketing, ainsi qu’une sortie audio directe. Importez des images de produits pour générer des vidéos publicitaires.
  • Fictions de qualité / bandes dessinées IA: Utilisez viduq3-drama. Sa cohérence des personnages, ses effets soignés et son expression réaliste des émotions conviennent à la production de contenus narratifs.
  • Usage général: Utilisez viduq3-mix. Son équilibre entre qualité visuelle et effets dynamiques convient à la plupart des scénarios vidéo à partir de références.
input object (obligatoire)L’entrée de base, comprenant des images de référence et un prompt.

Propriétés

prompt string (obligatoire)Le prompt textuel décrivant les éléments et caractéristiques visuelles souhaités dans la vidéo générée.Le chinois et l’anglais sont pris en charge. La longueur maximale est de 5 000 caractères. Le texte excédentaire est automatiquement tronqué.Exemple : dans un café, un homme est assis sur une chaise près d’une fenêtre, tenant une guitare et jouant une chanson folk country américaine apaisante.media array (obligatoire)Une liste de ressources multimédias indiquant les éléments de référence pour la génération vidéo.Chaque élément du tableau est un objet multimédia contenant les champs type et url.

Propriétés de l’élément

type string (obligatoire)Le type de ressource multimédia. Les valeurs valides dépendent du modèle sélectionné.

Fournir uniquement des images de référence

Modèles pris en charge: vidu/viduq3-ad_reference2video, vidu/viduq3-drama_reference2video, vidu/viduq3-mix_reference2videoLa valeur est fixée à :
  • image: Image de référence.
Limite des ressources : de 1 à 7 images.
url string (obligatoire)L’URL de la ressource multimédia.

Fournir une image (type=image)

L’URL de l’image de référence. Elle doit être accessible publiquement.Limites des images :
  • Formats : JPEG, JPG, PNG et WEBP.
  • Rapport d’aspect : de 1:4 à 4:1.
  • Taille du fichier : jusqu’à 50 Mo.
parameters object (obligatoire)Paramètres de génération vidéo, tels que la résolution et la durée.

Propriétés

resolution string (facultatif)
La résolution affecte directement la facturation. Avant d’appeler l’API, vérifiez les tarifs des modèles.
La résolution de la vidéo générée. Les valeurs valides dépendent du modèle sélectionné :
  • vidu/viduq3-ad_reference2video: 720P ou 1080P. Par défaut : 720P.
  • vidu/viduq3-drama_reference2video: 720P ou 1080P. Par défaut : 1080P.
  • vidu/viduq3-mix_reference2video: 720P ou 1080P. Par défaut : 720P.
size string (facultatif)La résolution de la vidéo générée, en pixels, au format width*height.La valeur par défaut dépend de resolution :
  • Lorsque resolution=720P, size vaut 1280*720 par défaut.
  • Lorsque resolution vaut 1080P, size vaut 1920*1080 par défaut.
Les rapports d’aspect pris en charge varient selon le modèle :
  • vidu/viduq3-drama_reference2video: Seuls 16:9 et 9:16 sont pris en charge.
  • Autres modèles : 16:9, 4:3, 1:1, 3:4 et 9:16 sont pris en charge.
Valeurs de size valides par niveau de résolution :
  • 720P
    • 16:9: 1280*720
    • 4:3: 1280*960
    • 1:1: 1280*1280
    • 3:4: 960*1280
    • 9:16: 720*1280
  • 1080P
    • 16:9: 1920*1080
    • 4:3: 1920*1440
    • 1:1: 1920*1920
    • 3:4: 1440*1920
    • 9:16: 1080*1920
duration integer (obligatoire)
La durée affecte directement la facturation, calculée à la seconde. Avant d’appeler l’API, vérifiez les tarifs des modèles.
La durée de la vidéo générée, en secondes.
  • vidu/viduq3-ad_reference2video: Un entier compris dans l’intervalle [3, 15]. La valeur par défaut est 5.
  • vidu/viduq3-drama_reference2video: Un entier compris dans l’intervalle [2, 15]. La valeur par défaut est 5.
    • Si le nombre de plans est trop élevé ou nettement trop faible par rapport à la durée, le modèle peut ajuster automatiquement la longueur de la vidéo pour préserver l’intégralité du récit. La durée réelle peut être supérieure ou inférieure à la valeur spécifiée.
    • La facturation est calculée selon la durée réelle de sortie.
  • vidu/viduq3-mix_reference2video: La valeur est un entier compris dans l’intervalle [1, 16]. La valeur par défaut est 5.
audio boolean (facultatif)Modèles pris en charge: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video.Indique s’il faut générer une vidéo avec audio. Si cette option est activée, le modèle génère automatiquement une musique de fond ou des effets sonores adaptés au contenu.
  • false: Valeur par défaut. La sortie est une vidéo sans son.
  • true: Produit une vidéo avec audio.
vidu/viduq3-drama_reference2video ne prend pas en charge ce paramètre. Ce modèle produit par défaut des vidéos avec audio.
watermark boolean (facultatif)Indique s’il faut ajouter un filigrane en bas à droite de la vidéo. Le texte est fixé à "Content generated by AI".
  • false: Valeur par défaut. Aucun filigrane n’est ajouté.
  • true: Ajoute un filigrane.
seedinteger(facultatif)La graine. L’intervalle de valeurs est [0, 2147483647].Si vous ne spécifiez pas de graine, le système en génère une aléatoirement. Pour améliorer la reproductibilité des résultats, nous recommandons une valeur fixe.Le modèle étant probabiliste, une même graine ne garantit pas des résultats identiques d’une exécution à l’autre.Exemple : 12345
  • Publicité (image uniquement)
  • Fiction (image uniquement)
  • Image uniquement
Modèle pris en charge: vidu/viduq3-ad_reference2video.
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": "vidu/viduq3-ad_reference2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/dtnctw/ad-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/bspdpd/ad-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mhsjyy/ad-3.png"
            }
        ],
        "prompt": "A yoga pants advertisement. The product is a pair of black high-waisted yoga pants with one pocket on each side. An Asian model happily says I will never wear yoga pants without pockets again. The video remains clear, stable, and easy to understand."
    },
    "parameters": {
        "duration": 8,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Paramètres de réponse

  • Réponse réussie
  • Réponse d’erreur
Conservez le task_id pour consulter 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 objectLes données de sortie de la tâche.

Propriétés

task_id stringL’ID de la tâche. Valable pour les requêtes pendant 24 heures.task_status stringL’é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, utilisé pour le suivi et le dépannage.
message stringMessage d’erreur détaillé. Renvoyé uniquement en cas d’échec de la requête. Consultez Codes d’erreur.

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

Région de Singapour: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Recommandation d’interrogation périodique: La génération vidéo peut prendre plusieurs minutes. Nous recommandons une interrogation périodique à un intervalle raisonnable (par exemple 15 secondes) pour obtenir le résultat.
  • Transitions d’état de la tâche: PENDING (en file d’attente) → RUNNING (en cours) → SUCCEEDED (réussi) / FAILED (échoué).
  • Durée de validité du task_id: 24 heures. Après expiration, le résultat ne peut plus être consulté et l’API renvoie l’état UNKNOWN.
  • Limite de RPS: L’API de consultation est limitée par défaut à 20 RPS. Pour des requêtes plus fréquentes ou des notifications d’événements, nous recommandons de configurer les rappels de tâches asynchrones.
  • Autres opérations: Pour consulter des tâches par lots ou les annuler, consultez Gérer les tâches asynchrones.

Paramètres de requête

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
task_id string (Obligatoire)L’ID de la tâche.
  • Consulter le résultat de la tâche
Remplacez {task_id} par la valeur task_id renvoyée par l’appel d’API précédent. Le task_id est valable pour les requêtes pendant 24 heures
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Paramètres de réponse

outputobjectLes données de sortie de la tâche.

Propriétés

task_id stringL’ID de la tâche. Valable pour les requêtes pendant 24 heures.task_status stringL’é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 pendant l’interrogation périodique :
  • PENDING → RUNNING → SUCCEEDED ou FAILED.
  • L’état initial 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 relancez la tâche.
submit_time stringL’heure d’envoi de la tâche. Format : YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringL’heure d’exécution de la tâche. Format : YYYY-MM-DD HH:mm:ss.SSS.end_time stringL’heure de fin de la tâche. Format : YYYY-MM-DD HH:mm:ss.SSS.video_urlstringL’URL de la vidéo. Ce paramètre est renvoyé uniquement lorsque task_status est SUCCEEDED.La vidéo est au format MP4 (encodage H.264). L’URL est valable 24 heures. Téléchargez la vidéo rapidement.orig_prompt stringLe prompt d’entrée original, correspondant au paramètre de requête prompt.code stringCode d’erreur. Renvoyé uniquement en cas d’échec de la requête. Consultez Codes d’erreur.message stringMessage d’erreur détaillé. Renvoyé uniquement en cas d’échec de la requête. Consultez Codes d’erreur.
usage objectStatistiques d’utilisation (uniquement pour les tâches réussies).

Propriétés

duration integerLa durée totale de la vidéo générée, utilisée pour la facturation.size stringSpécifie la résolution de la vidéo générée.fps integerSpécifie la fréquence d’images de la vidéo générée. La valeur est fixée à 24.SR stringSpécifie le niveau de résolution de la vidéo générée.audio booleanIndique si la vidéo générée contient de l’audio.video_count integerSpécifie le nombre de vidéos générées. La valeur est fixée à 1.reference_type stringSpécifie le type d’éléments de référence utilisés.
request_id stringIdentifiant unique de la requête, utilisé pour le suivi et le dépannage.
  • Tâche réussie
  • Échec de la tâche
  • Consultation de tâche expirée
Les URL vidéo ne sont valables que 24 heures, puis sont automatiquement supprimées. Enregistrez rapidement les vidéos générées.
{
    "request_id": "8f240644-efe8-43bf-86ff-xxxxxx",
    "output": {
        "task_id": "b7e05baa-c318-440d-b293-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 15:10:42.723",
        "scheduled_time": "2026-03-27 15:10:42.754",
        "end_time": "2026-03-27 15:11:17.388",
        "orig_prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "reference_type": "image,video",
        "SR": "540"
    }
}

Codes d’erreur

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

FAQ

Q : Dois-je fournir à la fois size et resolution ?

R : Non. Ces deux paramètres sont facultatifs, mais nous recommandons de fournir les deux pour contrôler précisément le rapport d’aspect de la vidéo générée. Consultez Valeurs valides de size. Si vous ne fournissez pas les deux, le système traite la requête comme suit :
  • Seul size est fourni: Le paramètre size est ignoré ; le système utilise resolution=720P et sa valeur de size par défaut (1280*720).
    Exemple : l’API renvoie size="1280*720" et SR=720.
  • Si vous fournissez uniquement resolution: La sortie utilise le niveau de résolution spécifié.
    Par exemple, avec resolution=540P, l’API renvoie size="960*528" et SR=540. Avec resolution=1080P, elle renvoie size="1920*1080" et SR=1080.