Audio and video translation - Qwen API reference

Nota: A interface DashScope não tem suporte.

Modelos compatíveis

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

Pré-requisitos

Antes de começar, conclua as etapas a seguir:

Crie uma chave de API
Configure a chave de API como variável de ambiente
Instale o SDK da OpenAI (para Python ou Node.js)

Endpoints

Região	SDKbase_url	Endpoint HTTP
Singapura	`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`
Pequim	`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`	`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions`

Substitua {WorkspaceId} pelo seu ID do workspace real.

O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Pequim) e Singapura. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para requisições de inferência. Recomendamos migrar para os novos domínios:

China (Pequim): de https://dashscope.aliyuncs.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapura: de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} é o ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.

Início rápido

Os exemplos a seguir traduzem um arquivo de áudio e retornam texto traduzido e áudio via streaming. Substitua o base_url se usar a região de Pequim.

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

Entrada de vídeo

Para traduzir vídeo em vez de áudio, defina o tipo de conteúdo como 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"
                },
            }
        ],
    },
]

Os demais parâmetros permanecem iguais.

Corpo da requisição

Parâmetros obrigatórios

Parâmetro	Tipo	Descrição
`model`	string	Nome do modelo. Valores válidos: `qwen3-livetranslate-flash`, `qwen3-livetranslate-flash-2025-12-01`.
`messages`	array	Array de mensagens. Apenas uma mensagem de usuário tem suporte.
`stream`	boolean	Deve ser `true`. O padrão é `false`, mas como apenas a saída em streaming tem suporte, defina este valor como `true`.
`translation_options`	object	Configuração de tradução. Consulte Opções de tradução. Este é um parâmetro fora do padrão OpenAI. No SDK Python, passe-o dentro de `extra_body`. Em Node.js ou HTTP, passe-o no nível superior.

Parâmetros opcionais

Parâmetro	Tipo	Padrão	Descrição
`modalities`	array	`["text"]`	Modalidade de saída. Defina como `["text", "audio"]` para receber saída em texto e áudio, ou `["text"]` para apenas texto.
`audio`	object	-	Configuração do áudio de saída. Obrigatório quando `modalities` inclui `"audio"`. Consulte Opções de saída de áudio.
`stream_options`	object	-	Configuração de streaming. Consulte Opções de streaming.
`max_tokens`	integer	Máximo do modelo	Número máximo de tokens a gerar. A geração para neste limite ou ao concluir.
`seed`	integer	-	Semente aleatória para reprodutibilidade. A mesma semente produz saída idêntica para requisições idênticas. Intervalo: `[0, 2^31-1]`.
`speech_rate`	float	1.0	Controla a velocidade do áudio de saída. 1.0 é a velocidade normal; valores menores que 1.0 tornam o áudio mais lento e maiores que 1.0, mais rápido. Intervalo: [0.5, 2.0].

Parâmetros de amostragem

Para garantir a precisão da tradução, mantenha estes parâmetros com os valores padrão.

Parâmetro	Tipo	Padrão	Intervalo	Observações
`temperature`	float	0.000001	[0, 2)	Controla a diversidade da saída.
`top_p`	float	0.8	(0, 1.0]	Limiar de amostragem de núcleo.
`presence_penalty`	float	0	[-2.0, 2.0]	Reduz repetições quando positivo.
`top_k`	integer	1	>= 0	Tamanho do conjunto de candidatos. Se o valor for `None` ou maior que 100, `top_k` é desativado e apenas `top_p` tem efeito. Parâmetro fora do padrão OpenAI. SDK Python: use `extra_body`.
`repetition_penalty`	float	1.05	> 0	Penaliza sequências repetidas. Parâmetro fora do padrão OpenAI. SDK Python: use `extra_body`.

Objeto de mensagem

O array messages deve conter exatamente um objeto com role definido como user. Propriedades dos itens do arraycontent:

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`input_audio` para entrada de áudio, `video_url` para entrada de vídeo.
`input_audio`	object	Quando `type` é `input_audio`	Entrada de áudio. Veja abaixo.
`video_url`	object	Quando `type` é `video_url`	Entrada de vídeo. Veja abaixo.

Objetoinput_audio:

Campo	Tipo	Obrigatório	Descrição
`data`	string	Sim	URL do arquivo de áudio ou URL de dados Base64. Para arquivos locais, consulte Inserir um arquivo local codificado em Base64.
`format`	string	Sim	Formato de áudio, como `mp3` ou `wav`.

Objetovideo_url:

Campo	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL pública do arquivo de vídeo ou URL de dados Base64. Para arquivos locais, consulte Inserir um arquivo local codificado em Base64.

Opções de tradução

Campo	Tipo	Obrigatório	Descrição
`source_lang`	string	Não	Nome completo em inglês do idioma de origem. Consulte Idiomas compatíveis. Se omitido, o sistema detecta o idioma automaticamente.
`target_lang`	string	Sim	Nome completo em inglês do idioma de destino. Consulte Idiomas compatíveis.

Nota: translation_options é um parâmetro fora do padrão OpenAI. No SDK Python, passe-o dentro de extra_body . Em Node.js ou HTTP, passe-o no nível superior do corpo da requisição.

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

Opções de saída de áudio

Obrigatório quando modalities é ["text", "audio"].

Campo	Tipo	Obrigatório	Descrição
`voice`	string	Sim	Voz para o áudio de saída. Consulte Vozes compatíveis.
`format`	string	Sim	Formato do áudio de saída. Apenas `wav` tem suporte.

Opções de streaming

Campo	Tipo	Padrão	Descrição
`include_usage`	boolean	`false`	Quando `true`, o último chunk inclui detalhes de uso de tokens.

Resposta

A API retorna uma série de chunks em streaming, cada um como um objeto chat.completion.chunk. Os chunks dividem-se em três categorias: texto, áudio e uso de tokens.

Chunk de texto

Contém texto traduzido incremental em 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 de áudio

Contém áudio incremental codificado em Base64 em 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 uso de tokens

Retornado como o último chunk quando include_usage é true. O array choices está vazio e usage contém o detalhamento dos 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
    }
  }
}

Nota: Para entrada de vídeo, prompt_tokens_details.audio_tokens inclui os tokens de áudio extraídos do vídeo. video_tokens informa a contagem de tokens específicos do vídeo.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Identificador da requisição. Idêntico em todos os chunks.
`choices`	array	Conteúdo gerado. Vazio no chunk final de uso.
`choices[].delta.content`	string	Texto traduzido incremental. `null` em chunks de áudio.
`choices[].delta.audio`	object	Dados de áudio incrementais. `null` em chunks de texto.
`choices[].delta.audio.data`	string	Segmento de áudio codificado em Base64.
`choices[].delta.audio.id`	string	Identificador único do áudio de saída.
`choices[].delta.audio.expires_at`	integer	Timestamp de criação da requisição.
`choices[].delta.role`	string	Função da mensagem. Presente apenas no primeiro chunk.
`choices[].finish_reason`	string	`stop` quando a geração termina normalmente; `length` quando truncada por `max_tokens`; `null` durante o processamento.
`choices[].index`	integer	Sempre `0`.
`created`	integer	Timestamp Unix da requisição. Idêntico em todos os chunks.
`model`	string	Nome do modelo.
`object`	string	Sempre `chat.completion.chunk`.
`usage`	object	Consumo de tokens. Presente apenas no último chunk quando `include_usage` é `true`.
`usage.prompt_tokens`	integer	Total de tokens de entrada.
`usage.completion_tokens`	integer	Total de tokens de saída.
`usage.total_tokens`	integer	Soma de `prompt_tokens` e `completion_tokens`.
`usage.completion_tokens_details.audio_tokens`	integer	Tokens de áudio de saída.
`usage.completion_tokens_details.text_tokens`	integer	Tokens de texto de saída.
`usage.prompt_tokens_details.audio_tokens`	integer	Tokens de áudio de entrada. Para entrada de vídeo, inclui o áudio extraído do vídeo.
`usage.prompt_tokens_details.text_tokens`	integer	Tokens de texto de entrada. Sempre `0`.
`usage.prompt_tokens_details.video_tokens`	integer	Tokens de vídeo de entrada. Presente apenas para entrada de vídeo.

Campos fixos como null

Os campos a seguir estão presentes na resposta para compatibilidade com OpenAI, mas sempre retornam null: reasoning_content, function_call, refusal, tool_calls, logprobs, service_tier, system_fingerprint

Notas de uso

Apenas streaming. Defina stream como true. Chamadas sem streaming não têm suporte.
Mensagem única. O array messages aceita apenas uma mensagem de usuário.
Parâmetros fora do padrão. translation_options, top_k e repetition_penalty não fazem parte da API padrão da OpenAI. SDK Python: passe em extra_body. Node.js/HTTP: inclua no nível superior.
Padrões de amostragem. Os valores padrão para temperature, top_p, top_k, presence_penalty e repetition_penalty são otimizados para precisão na tradução. Alterá-los pode reduzir a qualidade.
Formato do áudio de saída. Apenas wav tem suporte.
Detecção automática de idioma. Se você omitir source_lang, o sistema detectará o idioma de entrada automaticamente.

Referências

Visão geral da tradução de áudio e vídeo
Vozes compatíveis
Idiomas compatíveis
Seleção de modelo
Crie uma chave de API
Configure a chave de API como variável de ambiente
Instale o SDK
Inserir um arquivo local codificado em Base64

​Modelos compatíveis

​Pré-requisitos

​Endpoints

​Início rápido

​Python

​Node.js

​curl

​Entrada de vídeo

​Corpo da requisição

​Parâmetros obrigatórios

​Parâmetros opcionais

​Parâmetros de amostragem

​Objeto de mensagem

​Opções de tradução

​Opções de saída de áudio

​Opções de streaming

​Resposta

​Chunk de texto

​Chunk de áudio

​Chunk de uso de tokens

​Campos da resposta

​Campos fixos como null

​Notas de uso

​Referências