Referencia de la API para qwen3-livetranslate-flash - Alibaba Cloud Model Studio

qwen3-livetranslate-flash traduce audio y video a través del endpoint de finalizaciones de chat compatible con OpenAI. Todas las solicitudes se transmiten.

Nota: La interfaz DashScope no es compatible.

Modelos admitidos

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

Requisitos previos

Antes de comenzar, complete lo siguiente:

Crear una clave API
Configurar la clave API como variable de entorno
Instalar el SDK de OpenAI (para Python o Node.js)

Endpoints

Región	SDK`base_url`	Endpoint HTTP
Singapur	`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`
Beijing	`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`	`POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions`

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:

China (Pekín): de https://dashscope.aliyuncs.com a https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapur: de https://dashscope-intl.aliyuncs.com a https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. El dominio existente permanece totalmente funcional.

Inicio rápido

Los siguientes ejemplos traducen un archivo de audio y devuelven tanto texto traducido como audio mediante transmisión. Reemplace base_url si utiliza la región de Pekín.

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 video

Para traducir video en lugar de audio, establezca el tipo de contenido en 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"
                },
            }
        ],
    },
]

Todos los demás parámetros permanecen igual.

Cuerpo de la solicitud

Parámetros obligatorios

Parámetro	Tipo	Descripción
`model`	string	Nombre del modelo. Valores válidos: `qwen3-livetranslate-flash`, `qwen3-livetranslate-flash-2025-12-01`.
`messages`	array	Una matriz de mensajes. Solo se admite un mensaje de usuario.
`stream`	boolean	Debe ser `true`. El valor predeterminado es `false`, pero solo se admite la salida por transmisión, por lo que debe establecerlo en `true`.
`translation_options`	object	Configuración de traducción. Consulte Opciones de traducción. Este es un parámetro no estándar de OpenAI. En el SDK de Python, páselo dentro de `extra_body`. En Node.js o HTTP, páselo en el nivel superior.

Parámetros opcionales

Parámetro	Tipo	Predeterminado	Descripción
`modalities`	array	`["text"]`	Modalidad de salida. Establezca en `["text", "audio"]` para recibir salida de texto y audio, o `["text"]` para solo texto.
`audio`	object	-	Configuración de audio de salida. Obligatorio cuando `modalities` incluye `"audio"`. Consulte Opciones de salida de audio.
`stream_options`	object	-	Configuración de transmisión. Consulte Opciones de transmisión.
`max_tokens`	integer	Máximo del modelo	El número máximo de tokens a generar. La generación se detiene al alcanzar este límite o al completarse.
`seed`	integer	-	Semilla aleatoria para reproducibilidad. La misma semilla produce una salida idéntica para solicitudes idénticas. Rango: `[0, 2^31-1]`.
`speech_rate`	float	1.0	Controla la velocidad del audio de salida. 1.0 es velocidad normal, menos de 1.0 es más lento, mayor que 1.0 es más rápido. Rango: [0.5, 2.0].

Parámetros de muestreo

Para garantizar la precisión de la traducción, mantenga estos parámetros en sus valores predeterminados.

Parámetro	Tipo	Predeterminado	Rango	Notas
`temperature`	float	0.000001	[0, 2)	Controla la diversidad de la salida.
`top_p`	float	0.8	(0, 1.0]	Umbral de muestreo de núcleo.
`presence_penalty`	float	0	[-2.0, 2.0]	Reduce la repetición cuando es positivo.
`top_k`	integer	1	>= 0	Tamaño del conjunto de candidatos. Si el valor es `None` o mayor que 100, `top_k` se desactiva y solo `top_p` surte efecto. Parámetro no estándar de OpenAI. SDK de Python: use `extra_body`.
`repetition_penalty`	float	1.05	> 0	Penaliza secuencias repetidas. Parámetro no estándar de OpenAI. SDK de Python: use `extra_body`.

Objeto de mensaje

La matriz messages debe contener exactamente un objeto con role establecido en user.

Propiedades de los elementos de la matrizcontent:

Campo	Tipo	Obligatorio	Descripción
`type`	string	Sí	`input_audio` para entrada de audio, `video_url` para entrada de video.
`input_audio`	object	Cuando `type` es `input_audio`	Entrada de audio. Véase abajo.
`video_url`	object	Cuando `type` es `video_url`	Entrada de video. Véase abajo.

input_audioobject:

Campo	Tipo	Obligatorio	Descripción
`data`	string	Sí	URL del archivo de audio o una URL de datos Base64. Para archivos locales, consulte Introducir un archivo local codificado en Base64.
`format`	string	Sí	Formato de audio, como `mp3` o `wav`.

video_urlobject:

Campo	Tipo	Obligatorio	Descripción
`url`	string	Sí	URL pública del archivo de video o una URL de datos Base64. Para archivos locales, consulte Introducir un archivo local codificado en Base64.

Opciones de traducción

Campo	Tipo	Obligatorio	Descripción
`source_lang`	string	No	Nombre completo en inglés del idioma de origen. Consulte Idiomas admitidos. Si se omite, el idioma se detecta automáticamente.
`target_lang`	string	Sí	Nombre completo en inglés del idioma de destino. Consulte Idiomas admitidos.

Nota: translation_options es un parámetro no estándar de OpenAI. En el SDK de Python, páselo dentro de extra_body. En Node.js o HTTP, páselo en el nivel superior del cuerpo de la solicitud.

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

Opciones de salida de audio

Requerido cuando modalities es ["text", "audio"].

Campo	Tipo	Obligatorio	Descripción
`voice`	string	Sí	Voz para el audio de salida. Consulte Voces admitidas.
`format`	string	Sí	Formato de audio de salida. Solo se admite `wav`.

Opciones de transmisión

Campo	Tipo	Predeterminado	Descripción
`include_usage`	boolean	`false`	Cuando `true`, el fragmento final incluye detalles de uso de tokens.

Respuesta

La API devuelve una serie de fragmentos de transmisión, cada uno como un objeto chat.completion.chunk. Los fragmentos se dividen en tres categorías: texto, audio y uso de tokens.

Fragmento de texto

Contiene texto traducido incremental en 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"
}

Fragmento de audio

Contiene audio incremental codificado en Base64 en 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"
}

Fragmento de uso de tokens

Devuelto como el fragmento final cuando include_usage es true. La matriz choices está vacía y usage contiene el desglose de 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 video, prompt_tokens_details.audio_tokens incluye los tokens de audio extraídos del video. video_tokens reporta el recuento de tokens específicos del video.

Campos de respuesta

Campo	Tipo	Descripción
`id`	string	El identificador de la solicitud. Idéntico en todos los fragmentos.
`choices`	array	Contenido generado. Vacío en el fragmento final de uso.
`choices[].delta.content`	string	Texto traducido incremental. `null` en fragmentos de audio.
`choices[].delta.audio`	object	Datos de audio incrementales. `null` en fragmentos de texto.
`choices[].delta.audio.data`	string	Segmento de audio codificado en Base64.
`choices[].delta.audio.id`	string	Identificador único para el audio de salida.
`choices[].delta.audio.expires_at`	integer	Marca de tiempo en la que se creó la solicitud.
`choices[].delta.role`	string	Rol del mensaje. Presente solo en el primer fragmento.
`choices[].finish_reason`	string	`stop` cuando la generación se completa normalmente, `length` cuando se trunca por `max_tokens`, `null` mientras está en progreso.
`choices[].index`	integer	Siempre `0`.
`created`	integer	Marca de tiempo Unix para la solicitud. Idéntica en todos los fragmentos.
`model`	string	El nombre del modelo.
`object`	string	Siempre `chat.completion.chunk`.
`usage`	object	Consumo de tokens. Presente solo en el fragmento final cuando `include_usage` es `true`.
`usage.prompt_tokens`	integer	Total de tokens de entrada.
`usage.completion_tokens`	integer	Total de tokens de salida.
`usage.total_tokens`	integer	Suma de `prompt_tokens` y `completion_tokens`.
`usage.completion_tokens_details.audio_tokens`	integer	Tokens de audio de salida.
`usage.completion_tokens_details.text_tokens`	integer	Tokens de texto de salida.
`usage.prompt_tokens_details.audio_tokens`	integer	Tokens de audio de entrada. Para entrada de video, esto incluye el audio extraído del video.
`usage.prompt_tokens_details.text_tokens`	integer	Tokens de texto de entrada. Siempre `0`.
`usage.prompt_tokens_details.video_tokens`	integer	Tokens de video de entrada. Presente solo para entrada de video.

Campos fijados a null

Los siguientes campos están presentes en la respuesta por compatibilidad con OpenAI, pero siempre devuelven null:

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

Notas de uso

Solo transmisión. Establezca stream en true. Las llamadas sin transmisión no son compatibles.
Mensaje único. La matriz messages acepta solo un mensaje de usuario.
Parámetros no estándar. translation_options, top_k y repetition_penalty no forman parte de la API estándar de OpenAI. SDK de Python: páselos en extra_body. Node.js/HTTP: inclúyalos en el nivel superior.
Valores predeterminados de muestreo. Los valores predeterminados para temperature, top_p, top_k, presence_penalty y repetition_penalty están optimizados para la precisión de la traducción. Cambiarlos puede degradar la calidad.
Formato de audio de salida. Solo se admite wav.
Detección automática de idioma. Si se omite source_lang, el idioma de entrada se detecta automáticamente.

Referencias

Descripción general de la traducción de audio y video
Voces admitidas
Idiomas admitidos
Selección de modelo
Crear una clave API
Configurar la clave API como variable de entorno
Instalar el SDK
Introducir un archivo local codificado en Base64