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.
- Sélectionner un modèle: Vérifiez la région de votre modèle.
- Sélectionner une URL: Choisissez l’URL de point de terminaison correspondante. Les URL HTTP et du SDK DashScope sont prises en charge.
- Configurer une clé API: Sélectionnez une région, obtenez une clé API, puis configurez-la comme variable d’environnement.
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_idrenvoyé pour consulter le résultat. Letask_idest 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êteEn-têtes de requêteContent-Typestring (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.Corps de la requêtemodelstring (obligatoire)Le modèle à utiliser. Valeurs valides :
Guide de sélection du modèle
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 à :
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.
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 de la vidéo générée. Les valeurs valides dépendent du modèle sélectionné :
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 :
integer (obligatoire)La durée de la vidéo générée, en secondes.
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.
vidu/viduq3-drama_reference2video ne prend pas en charge ce paramètre. Ce modèle produit par défaut des vidéos avec audio. boolean (facultatif)Indique s’il faut ajouter un filigrane en bas à droite de la vidéo. Le texte est fixé à "Content generated by AI".
integer(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 |
Modèle pris en charge: vidu/viduq3-ad_reference2video. |
Paramètres de réponse |
Conservez le task_id pour consulter l’état et le résultat de la tâche. |
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
| |
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êteEn-têtes de requêteAuthorizationstring (Obligatoire)Authentifie la requête avec une clé API Model Studio. Exemple : Bearer sk-xxxx.Paramètres de chemintask_idstring (Obligatoire)L’ID 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 |
Paramètres de réponseoutputobjectLes 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
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.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.stringIdentifiant unique de la requête, utilisé pour le suivi et le dépannage. |
Les URL vidéo ne sont valables que 24 heures, puis sont automatiquement supprimées. Enregistrez rapidement les vidéos générées. |
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
sizeest ignoré ; le système utiliseresolution=720Pet sa valeur desizepar défaut (1280*720).Exemple : l’API renvoie
size="1280*720"etSR=720. -
Si vous fournissez uniquement
resolution: La sortie utilise le niveau de résolution spécifié.Par exemple, avec
resolution=540P, l’API renvoiesize="960*528"etSR=540. Avecresolution=1080P, elle renvoiesize="1920*1080"etSR=1080.