Skip to main content

Référence de l’API PixVerse - texte vers vidéo

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

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

Activation du service

  1. Accédez à la console Model Studio, recherchez PixVerse, trouvez la carte du modèle PixVerse et cliquez sur Activer maintenant.
  2. 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.
Le code d’exemple de cette rubrique s’applique à la région de Singapour.

Appels HTTP

La génération de vidéo à partir de texte 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.
  • 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.
Si 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.Valeurs valides :
  • pixverse/pixverse-v6-t2v
input object (Obligatoire)Les informations d’entrée de base, telles que 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-t2v : jusqu’à 5 000 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 paramètre size affecte directement le coût. Avant un appel, vérifiez les tarifs des modèles.
Le tableau suivant répertorie les valeurs valides selon les niveaux de résolution et les rapports d’aspect.

Modèle pixverse/pixverse-v6-t2v

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

duration integer (Obligatoire)
Le paramètre duration affecte directement le coût, facturé à la seconde. Avant un appel, vérifiez les tarifs des modèles.
La durée de la vidéo générée, en secondes.
  • pixverse/pixverse-v6-t2v : un entier compris dans l’intervalle [1, 15].
audio boolean (Facultatif)
Le paramètre audio affecte directement le coût. Avant un appel, vérifiez les tarifs des modèles.
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.
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é.
shot_type string (Facultatif)Modèle pris en charge : pixverse/pixverse-v6-t2v.Spécifie le type de plan de la vidéo générée. Ce paramètre détermine si la vidéo se compose d’un seul plan continu ou de plusieurs plans.
  • single: Valeur par défaut. Génère une vidéo à plan unique.
  • multi: Multi-plans. Le système découpe intelligemment les plans.
Conseil d’utilisation : le paramètre prompt est prioritaire sur shot_type. Pour obtenir les meilleurs résultats, nous recommandons que la valeur de ce paramètre soit cohérente avec la description du prompt.
  • Pour obtenir systématiquement une vidéo à plan unique : définissez shot_type="single" et décrivez une scène à plan unique dans le prompt.
  • Pour obtenir systématiquement une vidéo multi-plans : définissez shot_type="multi" et décrivez une scène multi-plans dans le prompt.
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.
  • Texte vers vidéo
  • Texte vers vidéo (multi-plans)
Modèle pris en charge : pixverse/pixverse-v6-t2v.
# 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-t2v",
    "input": {
        "prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame."
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "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 : 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 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 à 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}
  • 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 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 : 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 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_url stringL’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 n’est pas destiné à un stockage à long terme. 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 de la vidéo générée, en secondes, utilisée pour la facturation.size stringLa résolution de la vidéo générée.fps integerLa fréquence d’images de la vidéo générée.SR stringLe 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 integerLe nombre de vidéos générées. La valeur est fixée à 1.shot_type stringLe type de plan de la vidéo générée.
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": "19171ea5-9efb-4d35-93a1-xxxxxx",
    "output": {
        "task_id": "7ed706b7-a9a9-4319-820c-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 10:34:41.630",
        "scheduled_time": "2026-03-20 10:34:41.655",
        "end_time": "2026-03-20 10:35:12.725",
        "orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "shot_type": "single",
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Appels du SDK DashScope

Les noms de paramètres du SDK correspondent en grande partie à ceux de l’API HTTP. La structure des paramètres est adaptée aux spécificités de chaque langage de programmation. Les tâches texte vers vidéo prenant beaucoup de temps (généralement de 1 à 5 minutes), le SDK encapsule le processus d’appel asynchrone HTTP et prend en charge les modes d’appel synchrone et asynchrone.
Le temps réellement nécessaire dépend du nombre de tâches en file d’attente et de l’état d’exécution du service. Patientez jusqu’à l’obtention du résultat.

Appels du SDK Python

Assurez-vous que votre version du SDK Python DashScope n’est pas antérieure à 2.0.1 avant d’exécuter le code suivant.Une version antérieure peut provoquer des erreurs telles que "url error, please check url!". Pour mettre à jour le SDK, consultez Installer le SDK.
Région de Singapour: region="ap-southeast-1" Remplacez {WorkspaceId} par votre véritable ID d’espace de travail.
  • Appel synchrone
  • Appel asynchrone
Exemple de requête
import os
import dashscope
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",
)

def sample_sync_call_t2v():
    # Appelle l'API synchrone, qui retourne le résultat directement.
    print('Veuillez patienter...')
    # generate est un appel en une étape (soumet la tâche et attend sa fin) et retourne un Job terminé
    # audio ne fait pas partie de la signature nommée et est transmis via parameters
    try:
        job = client.videos.generate(model='pixverse/pixverse-v6-t2v',
                                     prompt='In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.',
                                     size='1280*720',
                                     duration=5,
                                     watermark=False,
                                     parameters={'audio': False})
        print(job)
        print(job.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_sync_call_t2v()
Exemple de réponse
video_url n’expire pas actuellement, mais n’est pas destiné à un stockage à long terme. Téléchargez la vidéo rapidement.
{
    "request_id": "2b68d32e-86c8-4383-8a18-xxxxxx",
    "task_id": "ec40bb42-02d4-44d8-bf35-xxxxxx",
    "status": "SUCCEEDED",
    "results": [
        {
            "video_url": "https://media.pixverseai.cn/xxx.mp4"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "size": "1280x720",
        "fps": 24,
        "audio": false,
        "SR": "720"
    }
}

Appels du SDK Java

Assurez-vous que votre version du SDK Java DashScope n’est pas antérieure à 2.22.6 avant d’exécuter le code suivant.Une version antérieure peut provoquer des erreurs telles que "url error, please check url!". Pour mettre à jour le SDK, consultez Installer le SDK.
Région de Singapour: Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"; Remplacez {WorkspaceId} par votre véritable ID d’espace de travail.
  • Appel synchrone
  • Appel asynchrone
Exemple de requête
// Replace {WorkspaceId} with your actual workspace ID.
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Text2Video {

    static {
        // The following is the URL for the Singapore region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
    // To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Create a video compositing task and wait for the task to complete.
     */
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("pixverse/pixverse-v6-t2v")
                        .prompt("In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.")
                        .size("1280*720")
                        .duration(5)
                        .audio(true)
                        .watermark(true)
                        .seed(12345)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            text2Video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}
Exemple de réponse
video_url n’expire pas actuellement, mais n’est pas destiné à un stockage à long terme. Téléchargez la vidéo rapidement.
{
    "request_id": "bd1109bd-6c63-4e62-8bb8-xxxxxx",
    "output": {
        "task_id": "72af7c13-dad5-4aaa-b85d-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://media.pixverseai.cn/xxx.mp4",
        "orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
        "submit_time": "2026-03-20 11:21:13.227",
        "scheduled_time": "2026-03-20 11:21:13.252",
        "end_time": "2026-03-20 11:21:43.924"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "size": "1280*720",
        "input_video_duration": 0.0,
        "output_video_duration": 0.0,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Codes d’erreur

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