Référence de l’API PixVerse - vidéo à partir de références - Alibaba Cloud Model Studio

Le modèle vidéo à partir de références de PixVerse accepte plusieurs images de référence. Il utilise un prompt textuel pour décrire la scène et intègre les personnages principaux des ressources dans une vidéo fluide.

ImportantCe document s’applique uniquement à la région de Singapour. Vous devez utiliser une clé API de cette région.

Activation du service

Accédez à la console Model Studio, recherchez PixVerse, trouvez la carte du modèle PixVerse et cliquez sur Activer maintenant.
Dans la fenêtre contextuelle, confirmez l’activation et l’autorisation.

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 qui appartiennent tous à 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.

RemarqueLe code d’exemple de cette rubrique s’applique à la région de Singapour.

Appels HTTP

La génération de vidéo à partir de références est une tâche de longue durée qui prend généralement de 1 à 5 minutes ; l’API utilise donc des appels asynchrones. Le processus comprend deux étapes principales : « Créer une tâche -> Interroger périodiquement le résultat ». Les étapes sont les suivantes :

Étape 1 : créer une tâche pour obtenir un ID de tâche

Région de Singapour: 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.

Remarque

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 plutôt 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.

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.

ImportantSi cet en-tête de requê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. Pour les spécifications de sortie des modèles, consultez Liste des modèles.

Valeurs valides :

pixverse/pixverse-v6-r2v

input object (Obligatoire)

Les informations d’entrée de base, comprenant les images de référence et le prompt.

Propriétés

prompt string (Obligatoire)

Le prompt textuel. Il décrit les éléments et les caractéristiques visuelles souhaités dans la vidéo générée.

Le chinois et l’anglais sont pris en charge. Chaque caractère chinois ou chaque lettre compte pour un caractère. L’encodage des caractères est UTF-8. Les caractères excédentaires sont automatiquement tronqués.

pixverse/pixverse-v6-r2v : jusqu’à 2 048 caractères.

Instructions de référence aux images : lorsque vous transmettez une image de référence dans le paramètre media, vous pouvez y faire directement référence dans le prompt à l’aide de @ref_name.

Le ref_name défini dans media doit être unique au sein d’une même requête et correspondre un à un aux références du prompt.
Règle de formatage : vous devez laisser un espace après @ref_name comme séparateur.

Exemples :

Prompt simple : un homme est assis sur une chaise près de la fenêtre, tenant une guitare, et joue une chanson folk country américaine apaisante à côté d’un café.
Prompt avec références : @man est assis sur une chaise près de la fenêtre, tenant @guitar , et joue une chanson folk country américaine apaisante à côté de @coffeeshop .

media array (Obligatoire)

Une liste de ressources multimédias indiquant les images de référence nécessaires à la génération de la 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. Valeur fixe :

image_url: Une URL d’image.

Limite du nombre de ressources : jusqu’à 7 images.

url string (Obligatoire)

L’URL de l’image de référence. L’URL doit être accessible publiquement.

Les protocoles HTTP et HTTPS sont pris en charge.
Exemple : https://xxx/xxx.jpg.

Contraintes de l’image :

Format : JPG, PNG ou WEBP.
Résolution : la largeur et la hauteur de l’image ne peuvent pas dépasser 10 000 pixels.
Taille du fichier : jusqu’à 20 Mo.

ref_name string (Facultatif)

L’identifiant nominatif du sujet de l’image de référence. Il permet de faire référence à l’image dans le prompt avec @ref_name. Jusqu’à 30 caractères.

parameters object (Obligatoire)

Les paramètres de génération vidéo, tels que la résolution, la durée et la génération ou non de l’audio.

Propriétés

size string (Obligatoire)

La résolution de la vidéo générée, au format width*height en pixels.

Le tableau suivant répertorie les valeurs valides selon les niveaux de résolution.

Modèle pixverse/pixverse-v6-r2v

Niveau de résolution	Rapport d’aspect	Valeur de size (largeur*hauteur)
360P	16:9	640*360
	4:3	640*480
	1:1	640*640
	3:4	480*640
	9:16	360*640
	3:2	640*432
	2:3	432*640
	21:9	640*288
540P	16:9	1024*576
	4:3	1024*768
	1:1	1024*1024
	3:4	768*1024
	9:16	576*1024
	3:2	1024*688
	2:3	688*1024
	21:9	1024*448
720P	16:9	1280*720
	4:3	1108*832
	1:1	960*960
	3:4	832*1108
	9:16	720*1280
	3:2	1200*800
	2:3	800*1200
	21:9	1280*560
1080P	16:9	1920*1080
	4:3	1664*1248
	1:1	1440*1440
	3:4	1248*1664
	9:16	1080*1920
	3:2	1776*1184
	2:3	1184*1776
	21:9	1920*832

Exemple : 1280*720.

duration integer (Obligatoire)

ImportantLe paramètre duration affecte directement le coût. Avant un appel, vérifiez les tarifs de PixVerse - vidéo à partir de références.

La durée de la vidéo générée, en secondes.

pixverse/pixverse-v6-r2v : un entier compris dans l’intervalle [1, 15].

Exemple : 5.

audio boolean (Facultatif)

ImportantLe paramètre audio affecte directement le coût. Avant un appel, vérifiez les tarifs de PixVerse - vidéo à partir de références.

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 de la vidéo.

false: Valeur par défaut. Produit une vidéo muette.
true: Produit une vidéo avec audio.

Exemple : false.

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 "AI Generated".

false: Valeur par défaut. Aucun filigrane n’est ajouté.
true: Un filigrane est ajouté.

Exemple : false.

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.

Vidéo à partir de références

Transmettez les images de référence via media, et définissez size et duration pour contrôler la résolution et la durée de la vidéo.

# Replace {WorkspaceId} with your actual workspace ID.
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": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Python SDK

import dashscope
import os
from dashscope.v2 import DashScopeError

# Voici la configuration de la région de Singapour. Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
    # Si la variable d'environnement n'est pas configurée, définissez directement votre API Key de Model Studio : api_key="sk-xxx"
    # Les API Key sont spécifiques à chaque région. Pour obtenir une API Key, consultez https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

media = [{'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png'}]

def sample_async_call():
    # Soumet la tâche de génération vidéo de manière asynchrone
    # audio ne fait pas partie de la signature nommée et est transmis via parameters
    try:
        job = client.videos.jobs.create(model='pixverse/pixverse-v6-r2v',
                                        media=media,
                                        prompt='A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop',
                                        size='1280*720',
                                        duration=5,
                                        watermark=True,
                                        parameters={'audio': False})
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"Code de statut HTTP: {e.status_code}")
        print(f"Code d'erreur: {e.code}")
        print(f"Message d'erreur: {e.message}")
        print("Consultez la documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
        return

    # Interroge l'état de la tâche
    try:
        snapshot = client.videos.jobs.fetch(job.task_id)
        print(snapshot.status)
    except DashScopeError as e:
        print(f"Code de statut HTTP: {e.status_code}")
        print(f"Code d'erreur: {e.code}")
        print(f"Message d'erreur: {e.message}")
        print("Consultez la documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

    # Attend la fin de la tâche
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.video_url)
    except DashScopeError as e:
        print(f"Code de statut HTTP: {e.status_code}")
        print(f"Code d'erreur: {e.code}")
        print(f"Message d'erreur: {e.message}")
        print("Consultez la documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call()

Vidéo à partir de références (avec ref_name)

Transmettez les images de référence dans media, et transmettez ref_name pour définir le nom du sujet de chaque image de référence.

# Replace {WorkspaceId} with your actual workspace ID.
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": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg",
                "ref_name": "man"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
                "ref_name": "guitar"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
                "ref_name": "coffeeshop"
            }
        ],
        "prompt": "@man sits on a chair by the window, holding @guitar , playing a soothing American country folk song next to @coffeeshop "
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Paramètres de réponse

output object

Informations de sortie de la tâche.

Propriétés

task_id string

L’ID de la tâche. Valable pour les requêtes pendant 24 heures.

task_status string

L’état de la tâche.

Valeurs d’énumération

PENDING : la tâche est en file d’attente.
RUNNING : la tâche est en cours de traitement.
SUCCEEDED : la tâche a réussi.
FAILED : la tâche a échoué.
CANCELED : la tâche a été annulée.
UNKNOWN : la tâche n’existe pas ou son état est inconnu.

request_id string

Identifiant unique de la requête, utilisé pour le suivi et le dépannage.

code string

Code d’erreur. Renvoyé uniquement en cas d’échec de la requête. Consultez Codes d’erreur.

message string

Message d’erreur détaillé. Renvoyé uniquement en cas d’échec de la requête. Consultez Codes d’erreur.

Réponse réussie

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"
}

Réponse d’erreur

La création de la tâche a échoué. Consultez Codes d’erreur.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Étape 2 : consulter le résultat à l’aide de l’ID de tâche

Région de Singapour: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Remarque

Recommandation d’interrogation périodique: La génération vidéo peut prendre plusieurs minutes. Utilisez un mécanisme d’interrogation périodique et consultez 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 l’API renvoie l’état de tâche 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. 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"

Paramètres de réponse

output object

Informations de sortie de la tâche.

Propriétés

task_id string

L’ID de la tâche. Valable pour les requêtes pendant 24 heures.

task_status string

L’état de la tâche.

Valeurs d’énumération

PENDING : la tâche est en file d’attente.
RUNNING : la tâche est en cours de traitement.
SUCCEEDED : la tâche a réussi.
FAILED : la tâche a échoué.
CANCELED : la tâche a été annulée.
UNKNOWN : la tâche n’existe pas ou son état est inconnu.

Transitions d’état pendant l’interrogation périodique :

PENDING (en file d’attente) → RUNNING (en cours) → SUCCEEDED (réussi) / FAILED (échoué).
L’état de la première consultation est généralement PENDING (en file d’attente) ou RUNNING (en cours).
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.
Si l’état est CANCELED, la tâche a été annulée. Pour continuer, soumettez de nouveau la tâche.
Si l’état est UNKNOWN, la tâche n’existe pas ou son état est inconnu. Cela peut se produire si le task_id n’existe pas ou si sa période de validité de 24 heures est dépassée.

submit_time string

L’heure d’envoi de la tâche. Format : YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

L’heure d’exécution de la tâche. Format : YYYY-MM-DD HH:mm:ss.SSS.

end_time string

L’heure de fin de la tâche. Format : YYYY-MM-DD HH:mm:ss.SSS.

video_url string

L’URL de la vidéo. Renvoyée uniquement lorsque task_status est SUCCEEDED.

La vidéo est au format MP4 (encodage H.264). Le lien de la vidéo n’expire pas actuellement, mais ne vous y fiez pas pour un stockage à long terme. Téléchargez la vidéo rapidement.

orig_prompt string

Le prompt d’entrée original, correspondant au paramètre de requête prompt.

code string

Code d’erreur. Renvoyé uniquement en cas d’échec de la requête. Consultez Codes d’erreur.

message string

Message d’erreur détaillé. Renvoyé uniquement en cas d’échec de la requête. Consultez Codes d’erreur.

usage object

Statistiques d’utilisation de la sortie, comptabilisées uniquement pour les tâches réussies.

Propriétés

duration integer

La durée totale de la vidéo générée, utilisée pour la facturation.

size string

La résolution de la vidéo générée.

fps integer

La fréquence d’images de la vidéo générée.

SR string

Le niveau de résolution de la vidéo générée.

audio boolean

Indique si la vidéo générée contient de l’audio.

video_count integer

Le nombre de vidéos générées. La valeur est fixée à 1.

request_id string

Identifiant unique de la requête, utilisé pour le suivi et le dépannage.

Tâche réussie

{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-10 15:03:25.848",
        "scheduled_time": "2026-03-10 15:03:25.884",
        "end_time": "2026-03-10 15:04:05.882",
        "orig_prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Échec de la tâche

Lorsqu’une tâche échoue, task_status vaut FAILED et un code ainsi qu’un message d’erreur sont renvoyés. Consultez Codes d’erreur.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

Consultation de tâche expirée

Le task_id est valable 24 heures. Passé ce délai, les requêtes renvoient l’erreur suivante.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

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 : Comment optimiser le résultat si le prompt ne donne pas de bons résultats ?

R : Essayez d’utiliser @ref_name comme alternative.

Méthode par défaut : utilisez directement le prompt. Le modèle analyse automatiquement le contenu de l’image de référence dans son ensemble, ce qui convient à la plupart des scénarios courants.
Méthode alternative : si le résultat généré s’écarte de vos attentes, utilisez @ref_name pour désigner l’image de référence dans le prompt afin d’améliorer le résultat.

Q : Comment utiliser ref_name ?

R : ref_name crée une liaison entre une image de référence et le prompt. Après avoir défini ref_name pour une image dans le tableau media, vous pouvez faire référence au sujet correspondant de l’image de référence dans le prompt à l’aide de la syntaxe @ref_name.

Par exemple, si vous définissez "ref_name": "kitten" dans media, utilisez @kitten dans le prompt pour faire référence à ce sujet. Remarque : vous devez laisser un espace après @kitten.
Exemple : @kitten et @puppy jouent sur l’herbe.