API reference for qwen3-livetranslate-flash - Alibaba Cloud Model Studio

qwen3-livetranslate-flash traduit du contenu audio et vidéo via l'endpoint chat completions compatible OpenAI. Toutes les requêtes s'effectuent en streaming.

Note : L'interface DashScope n'est pas prise en charge.

Modèles pris en charge

qwen3-livetranslate-flash
qwen3-livetranslate-flash-2025-12-01

Prérequis

Avant de commencer, procédez comme suit :

Créer une clé API
Configurer la clé API comme variable d'environnement
Installer le SDK OpenAI (pour Python ou Node.js)

Endpoints

Région	SDKbase_url	Endpoint HTTP
Singapour	`https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`	`POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions`
Pékin	`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`	`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions`

Remplacez {WorkspaceId} par votre ID d'espace de travail.

ImportantAlibaba Cloud Model Studio a publié des domaines spécifiques à chaque espace de travail pour les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :

Chine (Pékin) : passez de https://dashscope.aliyuncs.com à https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapour : passez de https://dashscope-intl.aliyuncs.com à https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} correspond à votre ID d'espace de travail, disponible sur la page Workspace Details dans la console Alibaba Cloud Model Studio. Le domaine existant reste pleinement fonctionnel.

Démarrage rapide

Les exemples suivants traduisent un fichier audio et renvoient à la fois le texte traduit et l'audio en streaming. Remplacez la valeur base_url si vous utilisez la région Pékin.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3-livetranslate-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250211/tixcef/cherry.wav",
                        "format": "wav",
                    },
                }
            ],
        }
    ],
    modalities=["text", "audio"],
    audio={"voice": "Cherry", "format": "wav"},
    stream=True,
    stream_options={"include_usage": True},
    extra_body={"translation_options": {"source_lang": "zh", "target_lang": "en"}},
)

for chunk in completion:
    print(chunk)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    // The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});

async function main() {
    const completion = await client.chat.completions.create({
        model: "qwen3-livetranslate-flash",
        messages: [
            {
                role: "user",
                content: [
                    {
                        type: "input_audio",
                        input_audio: {
                            data: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250211/tixcef/cherry.wav",
                            format: "wav",
                        },
                    },
                ],
            },
        ],
        modalities: ["text", "audio"],
        audio: { voice: "Cherry", format: "wav" },
        stream: true,
        stream_options: { include_usage: true },
        translation_options: { source_lang: "zh", target_lang: "en" },
    });

    for await (const chunk of completion) {
        console.log(JSON.stringify(chunk));
    }
}

main();

curl

## The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-livetranslate-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250211/tixcef/cherry.wav",
              "format": "wav"
            }
          }
        ]
      }
    ],
    "modalities": ["text", "audio"],
    "audio": {
      "voice": "Cherry",
      "format": "wav"
    },
    "stream": true,
    "stream_options": {
      "include_usage": true
    },
    "translation_options": {
      "source_lang": "zh",
      "target_lang": "en"
    }
  }'

Entrée vidéo

Pour traduire une vidéo plutôt qu'un fichier audio, définissez le type de contenu sur video_url :

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "video_url",
                "video_url": {
                    "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4"
                },
            }
        ],
    },
]

Tous les autres paramètres restent identiques.

Corps de la requête

Paramètres obligatoires

Paramètre	Type	Description
`model`	string	Nom du modèle. Valeurs valides : `qwen3-livetranslate-flash`, `qwen3-livetranslate-flash-2025-12-01`.
`messages`	array	Tableau de messages. Un seul message utilisateur est pris en charge.
`stream`	boolean	Doit être défini sur `true`. La valeur par défaut est `false`, mais seule la sortie en streaming est prise en charge ; vous devez donc définir ce paramètre sur `true`.
`translation_options`	object	Configuration de la traduction. Consultez Options de traduction. Il s'agit d'un paramètre non standard OpenAI. Dans le SDK Python, transmettez-le dans `extra_body`. Pour Node.js ou HTTP, placez-le au niveau supérieur.

Paramètres facultatifs

Paramètre	Type	Valeur par défaut	Description
`modalities`	array	`["text"]`	Modalité de sortie. Définissez sur `["text", "audio"]` pour recevoir à la fois du texte et de l'audio, ou sur `["text"]` pour obtenir uniquement du texte.
`audio`	object	-	Configuration audio de sortie. Obligatoire lorsque `modalities` inclut `"audio"`. Consultez Options de sortie audio.
`stream_options`	object	-	Configuration du streaming. Consultez Options de streaming.
`max_tokens`	integer	Maximum du modèle	Nombre maximal de tokens à générer. La génération s'arrête à cette limite ou lorsqu'elle est terminée.
`seed`	integer	-	Graine aléatoire pour la reproductibilité. Une même graine produit une sortie identique pour des requêtes identiques. Plage : `[0, 2^31-1]`.
`speech_rate`	float	1,0	Contrôle la vitesse de l'audio de sortie. 1,0 correspond à la vitesse normale, une valeur inférieure à 1,0 ralentit la lecture, tandis qu'une valeur supérieure à 1,0 l'accélère. Plage : [0,5, 2,0].

Paramètres d'échantillonnage

Pour garantir la précision de la traduction, conservez les valeurs par défaut de ces paramètres.

Paramètre	Type	Valeur par défaut	Plage	Notes
`temperature`	float	0,000001	[0, 2)	Contrôle la diversité de la sortie.
`top_p`	float	0,8	(0, 1,0]	Seuil d'échantillonnage du noyau.
`presence_penalty`	float	0	[-2,0, 2,0]	Réduit les répétitions lorsqu'il est positif.
`top_k`	integer	1	>= 0	Taille de l'ensemble des candidats. Si la valeur est `None` ou supérieure à 100, `top_k` est désactivé et seul `top_p` prend effet. Paramètre non standard OpenAI. SDK Python : utilisez `extra_body`.
`repetition_penalty`	float	1,05	> 0	Pénalise les séquences répétées. Paramètre non standard OpenAI. SDK Python : utilisez `extra_body`.

Objet Message

Le tableau messages doit contenir exactement un objet dont le champ role est défini sur user.

Propriétés des éléments du tableaucontent:

Champ	Type	Obligatoire	Description
`type`	string	Oui	`input_audio` pour une entrée audio, `video_url` pour une entrée vidéo.
`input_audio`	object	Lorsque `type` vaut `input_audio`	Entrée audio. Voir ci-dessous.
`video_url`	object	Lorsque `type` vaut `video_url`	Entrée vidéo. Voir ci-dessous.

Objet input_audio:

Champ	Type	Obligatoire	Description
`data`	string	Oui	URL du fichier audio ou URL de données Base64. Pour les fichiers locaux, consultez Fournir un fichier local encodé en Base64.
`format`	string	Oui	Format audio, tel que `mp3` ou `wav`.

Objet video_url:

Champ	Type	Obligatoire	Description
`url`	string	Oui	URL publique du fichier vidéo ou URL de données Base64. Pour les fichiers locaux, consultez Fournir un fichier local encodé en Base64.

Options de traduction

Champ	Type	Obligatoire	Description
`source_lang`	string	Non	Nom complet en anglais de la langue source. Consultez Langues prises en charge. Si ce champ est omis, la langue est détectée automatiquement.
`target_lang`	string	Oui	Nom complet en anglais de la langue cible. Consultez Langues prises en charge.

Note : translation_options est un paramètre non standard OpenAI. Dans le SDK Python, transmettez-le dans extra_body . Pour Node.js ou HTTP, placez-le au niveau supérieur du corps de la requête.

extra_body={"translation_options": {"source_lang": "zh", "target_lang": "en"}}

Options de sortie audio

Obligatoire lorsque modalities vaut ["text", "audio"].

Champ	Type	Obligatoire	Description
`voice`	string	Oui	Voix pour l'audio de sortie. Consultez Voix prises en charge.
`format`	string	Oui	Format audio de sortie. Seul le format `wav` est pris en charge.

Options de streaming

Champ	Type	Valeur par défaut	Description
`include_usage`	boolean	`false`	Lorsque la valeur est `true`, le dernier chunk inclut les détails de consommation des tokens.

Réponse

L'API renvoie une série de chunks en streaming, chacun étant un objet chat.completion.chunk. Ces chunks se divisent en trois catégories : texte, audio et consommation de tokens.

Chunk texte

Contient le texte traduit incrémentiel dans choices[0].delta.content :

{
  "id": "chatcmpl-c22a54b8-40cc-4a1d-988b-f84cdf86868f",
  "choices": [
    {
      "delta": {
        "content": " of",
        "role": null,
        "audio": null
      },
      "finish_reason": null,
      "index": 0
    }
  ],
  "created": 1764755440,
  "model": "qwen3-livetranslate-flash",
  "object": "chat.completion.chunk"
}

Chunk audio

Contient l'audio incrémentiel encodé en Base64 dans choices[0].delta.audio.data :

{
  "id": "chatcmpl-c22a54b8-40cc-4a1d-988b-f84cdf86868f",
  "choices": [
    {
      "delta": {
        "content": null,
        "role": null,
        "audio": {
          "data": "///+//7////+////////////AAAAAAAAAAABA......",
          "expires_at": 1764755440,
          "id": "audio_c22a54b8-40cc-4a1d-988b-f84cdf86868f"
        }
      },
      "finish_reason": null,
      "index": 0
    }
  ],
  "created": 1764755440,
  "model": "qwen3-livetranslate-flash",
  "object": "chat.completion.chunk"
}

Chunk de consommation des tokens

Renvoyé comme dernier chunk lorsque include_usage vaut true. Le tableau choices est vide, et usage contient le détail des tokens :

{
  "id": "chatcmpl-c22a54b8-40cc-4a1d-988b-f84cdf86868f",
  "choices": [],
  "created": 1764755440,
  "model": "qwen3-livetranslate-flash",
  "object": "chat.completion.chunk",
  "usage": {
    "completion_tokens": 242,
    "prompt_tokens": 415,
    "total_tokens": 657,
    "completion_tokens_details": {
      "accepted_prediction_tokens": null,
      "audio_tokens": 191,
      "reasoning_tokens": null,
      "rejected_prediction_tokens": null,
      "text_tokens": 51
    },
    "prompt_tokens_details": {
      "audio_tokens": 415,
      "cached_tokens": null,
      "text_tokens": 0,
      "video_tokens": null
    }
  }
}

Note : Pour une entrée vidéo, prompt_tokens_details.audio_tokens inclut les tokens audio extraits de la vidéo. video_tokens indique le nombre de tokens spécifiques à la vidéo.

Champs de réponse

Champ	Type	Description
`id`	string	Identifiant de la requête. Identique dans tous les chunks.
`choices`	array	Contenu généré. Vide dans le dernier chunk de consommation.
`choices[].delta.content`	string	Texte traduit incrémentiel. Vaut `null` dans les chunks audio.
`choices[].delta.audio`	object	Données audio incrémentielles. Vaut `null` dans les chunks texte.
`choices[].delta.audio.data`	string	Segment audio encodé en Base64.
`choices[].delta.audio.id`	string	Identifiant unique de l'audio de sortie.
`choices[].delta.audio.expires_at`	integer	Horodatage de création de la requête.
`choices[].delta.role`	string	Rôle du message. Présent uniquement dans le premier chunk.
`choices[].finish_reason`	string	`stop` lorsque la génération se termine normalement, `length` lorsqu'elle est tronquée par `max_tokens`, et `null` tant qu'elle est en cours.
`choices[].index`	integer	Toujours `0`.
`created`	integer	Horodatage Unix de la requête. Identique dans tous les chunks.
`model`	string	Nom du modèle.
`object`	string	Toujours `chat.completion.chunk`.
`usage`	object	Consommation de tokens. Présent uniquement dans le dernier chunk lorsque `include_usage` vaut `true`.
`usage.prompt_tokens`	integer	Total des tokens d'entrée.
`usage.completion_tokens`	integer	Total des tokens de sortie.
`usage.total_tokens`	integer	Somme de `prompt_tokens` et `completion_tokens`.
`usage.completion_tokens_details.audio_tokens`	integer	Tokens audio de sortie.
`usage.completion_tokens_details.text_tokens`	integer	Tokens texte de sortie.
`usage.prompt_tokens_details.audio_tokens`	integer	Tokens audio d'entrée. Pour une entrée vidéo, cela inclut l'audio extrait de la vidéo.
`usage.prompt_tokens_details.text_tokens`	integer	Tokens texte d'entrée. Toujours `0`.
`usage.prompt_tokens_details.video_tokens`	integer	Tokens vidéo d'entrée. Présent uniquement pour une entrée vidéo.

Champs fixés à null

Les champs suivants sont présents dans la réponse pour assurer la compatibilité OpenAI, mais renvoient toujours null :

reasoning_content, function_call, refusal, tool_calls, logprobs, service_tier, system_fingerprint

Notes d'utilisation

Streaming uniquement. Définissez stream sur true. Les appels sans streaming ne sont pas pris en charge.
Message unique. Le tableau messages accepte un seul message utilisateur.
Paramètres non standard. translation_options, top_k et repetition_penalty n'appartiennent pas à l'API OpenAI standard. SDK Python : transmettez-les dans extra_body. Node.js/HTTP : incluez-les au niveau supérieur.
Valeurs par défaut d'échantillonnage. Les valeurs par défaut de temperature, top_p, top_k, presence_penalty et repetition_penalty sont optimisées pour la précision de la traduction. Leur modification peut dégrader la qualité.
Format audio de sortie. Seul le format wav est pris en charge.
Détection automatique de la langue. Si source_lang est omis, la langue d'entrée est détectée automatiquement.

Références

Présentation de la traduction audio et vidéo
Voix prises en charge
Langues prises en charge
Sélection du modèle
Créer une clé API
Configurer la clé API comme variable d'environnement
Installer le SDK
Fournir un fichier local encodé en Base64