Skip to main content

Référence de l’API Vidu - image vers vidéo à partir d’une image initiale

Le modèle image vers vidéo de Vidu génère une vidéo fluide à partir d’une image et d’un prompt textuel.

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

La génération de vidéo à partir d’une image prend généralement de 1 à 5 minutes ; l’API utilise donc un modèle asynchrone. Le processus comprend deux étapes principales : créer une tâche, puis 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
Content-Type string (Obligatoire)Le type de contenu de la requête. Doit être application/json.Content-Type string (Obligatoire)Le type de contenu de la requête. Doit être application/json.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 nom du modèle. Valeurs valides :
  • vidu/viduq2-pro-fast_img2video
input object (Obligatoire)L’entrée de base, comprenant le prompt textuel et les ressources multimédias.

Propriétés

prompt string (Facultatif)Le prompt textuel décrivant les éléments et caractéristiques visuelles souhaités dans la vidéo générée.La longueur maximale est de 5 000 caractères (chaque caractère chinois et chaque lettre anglaise comptent pour un). Le texte excédentaire est tronqué.media array (Obligatoire)Une liste de ressources multimédias indiquant l’image à utiliser pour la génération.Chaque élément du tableau est un objet multimédia contenant les champs type et url.

Propriétés

type string (Obligatoire)Le type de ressource multimédia. Il doit être défini sur la valeur fixe suivante :
  • image: Une URL d’image.
Limite des ressources : fournissez exactement une image.url string (Obligatoire)L’URL du fichier image, qui doit être accessible publiquement.
  • Protocoles pris en charge : HTTP ou HTTPS.
  • Exemple : https://example.com/image.jpg.
Contraintes de l’image :
  • Formats : JPG, JPEG, PNG, WEBP.
  • Rapport d’aspect : de 1:4 à 4:1.
  • Taille du fichier : jusqu’à 50 Mo.
parameters object (Facultatif)Paramètres de traitement vidéo, tels que la résolution et la durée.

Propriétés

resolution string (Facultatif)
Le réglage de resolution affecte directement le coût. Avant un appel, vérifiez les tarifs des modèles.
Spécifie le niveau de résolution de la vidéo générée.Le modèle redimensionne la vidéo pour obtenir un nombre de pixels proche du niveau sélectionné, tout en conservant le rapport d’aspect de l’image d’entrée.Les valeurs valides sont 720P et 1080P. La valeur par défaut est 720P.duration integer (Facultatif)
Le réglage de duration affecte directement le coût, facturé à la seconde. Une durée plus longue entraîne un coût supérieur. Avant un appel, vérifiez les tarifs des modèles.
La durée de la vidéo générée, en secondes.Un entier compris dans l’intervalle [1, 10]. La valeur par défaut est 5.audio boolean (Facultatif)watermark boolean (Facultatif)Indique s’il faut ajouter un filigrane. Il est placé en bas à droite de la vidéo et contient le texte fixe "Generated by AI".
  • false: (Par défaut) Aucun filigrane n’est ajouté.
  • true: Un filigrane est ajouté.
seed integer (Facultatif)La graine aléatoire doit être un entier compris dans l’intervalle [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é.La génération du modèle étant probabiliste, une même graine ne garantit pas des résultats identiques.
  • Image vers vidéo
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/viduq2-pro-fast_img2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720P",
        "watermark": true
    }
}'

Paramètres de réponse

output objectInformations 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.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.
  • 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"
}

Étape 2 : consulter le résultat

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. Interrogez le résultat à un intervalle raisonnable, par exemple toutes les 15 secondes.
  • Évolution de l’état de la tâche: PENDING (en file d’attente) → RUNNING (en cours) → SUCCEEDED (réussi) / FAILED (échoué).
  • Validité de l’ID de tâche: Le task_id est valable 24 heures. Passé ce délai, les requêtes échouent et renvoient l’état UNKNOWN.
  • Limite de RPS: Le point de terminaison de consultation est limité par défaut à 20 RPS. Pour des requêtes fréquentes ou des notifications d’événements, configurez les rappels de tâches asynchrones.
  • Autres opérations: Pour les consultations par lots, l’annulation de tâches et d’autres opérations, consultez Gérer les tâches asynchrones.

Paramètres de requête

En-têtes
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

outputobjectInformations 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.end_time stringL’heure de fin de la tâche. Format : YYYY-MM-DD HH:mm:ss.SSS.orig_prompt stringURL de la vidéo. Renvoyée uniquement lorsque task_status est SUCCEEDED.Le format vidéo est MP4 (encodage H.264). Le lien 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 de la sortie, comptabilisées uniquement pour les tâches réussies.

Propriétés

duration integerLa durée totale facturable de la vidéo, en secondes.output_video_durationintegerLa durée de la vidéo de sortie, en secondes.size stringLa résolution de la vidéo de sortie.fps integerLa fréquence d’images de la vidéo de sortie. Elle est fixée à 24.SR stringLe niveau de résolution de la vidéo de sortie.audio booleanIndique si la vidéo de sortie contient de l’audio.video_count integerLe nombre de vidéos de sortie. Il est fixé à 1.
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
{
    "request_id": "3606f9f4-b833-44ec-8385-xxxxxx",
    "output": {
        "task_id": "2846881f-0496-4288-947f-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 14:25:32.057",
        "scheduled_time": "2026-03-27 14:25:32.084",
        "end_time": "2026-03-27 14:28:29.600",
        "orig_prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 5,
        "size": "990*932",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Codes d’erreur

Si un appel au modèle échoue, consultez Messages d’erreur pour résoudre le problème.