qwen3-livetranslate-flash 的 API 參考 - Alibaba Cloud Model Studio

本文介紹通過 OpenAI 相容介面調用 qwen3-livetranslate-flash 模型的輸入與輸出參數。

相關文檔：音視頻檔案翻譯-千問

不支援通過 DashScope 介面調用。

OpenAI 相容

新加坡地區

SDK 調用配置的base_url為：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

HTTP 調用配置的endpoint：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions

北京地區

SDK 調用配置的base_url為：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

HTTP 調用配置的endpoint：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions

重要阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：

華北2（北京）地區：從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地區：從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

其中 {WorkspaceId} 為您的業務空間 ID，可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

您需要已擷取API Key並配置API Key到環境變數。若通過OpenAI SDK進行調用，需要安裝SDK。

請求體

modelstring（必選）

模型名稱。支援的模型：qwen3-livetranslate-flash、qwen3-livetranslate-flash-2025-12-01。

messagesarray（必選）

訊息數組，用於向大模型傳遞上下文。僅支援傳入一個 User Message。

訊息類型

User Messageobject（必選）

使用者訊息。

屬性

contentarray（必選）

訊息內容。

屬性

typestring（必選）

可選值：

input_audio

輸入音頻時需設為input_audio。
video_url

輸入視頻檔案時需設為video_url。

input_audioobject

輸入的音頻資訊。當type為input_audio時是必選參數。

屬性

data string（必選）

音訊 URL 或Base64 Data URL。傳入本地檔案請參見：輸入 Base 64 編碼的本地檔案。

formatstring（必選）

輸入音訊格式，如mp3、wav等。

video_urlobject

輸入的視頻檔案資訊。當type為video_url時是必選參數。

屬性

url string（必選）

視頻檔案的公網 URL 或 Base64 Data URL。輸入本地視頻檔案請參見輸入 Base 64 編碼的本地檔案。

rolestring（必選）

使用者訊息的角色，固定為user。

streamboolean（必選） 預設值為 false

是否以流式方式輸出回複。模型僅支援流式輸出方式調用，僅可設為true。

stream_optionsobject（可選）

流式輸出的配置項，僅在 stream 為 true 時生效。

屬性

include_usageboolean（可選）預設值為 false

是否在最後一個資料區塊包含Token消耗資訊。

可選值：

true：包含；
false：不包含。

modalitiesarray（可選）預設值為["text"]

輸出資料的模態。可選值：

["text","audio"]：輸出文本與音頻；
["text"]：僅輸出文本。

audioobject（可選）

輸出音訊音色與格式。modalities參數需為["text","audio"]。

屬性

voicestring （必選）

輸出音訊音色。請參見支援的音色。

formatstring （必選）

輸出音訊格式，僅支援設定為wav。

max_tokensinteger（可選）

用於限制模型輸出的最大 Token 數。若產生內容超過此值，響應將被截斷。

預設值與最大值均為模型的最大輸出長度，請參見模型選型。

seedinteger（可選）

隨機數種子。用於確保在相同輸入和參數下產生結果可複現。若調用時傳入相同的 seed 且其他參數不變，模型將儘可能返回相同結果。

取值範圍：[0,2 31 −1]。

speech_ratefloat（可選）預設值為1.0

控制輸出音訊語速。1.0為正常語速，小於1.0為慢速，大於1.0為快速。

取值範圍：[0.5, 2.0]。

temperaturefloat（可選）預設值為0.000001

採樣溫度，控制模型產生內容的多樣性。temperature越高，產生的內容更多樣，反之更確定。

取值範圍： [0, 2)

為了翻譯的準確性，不建議修改該值。

top_pfloat（可選）預設值為0.8

核採樣的機率閾值，控制模型產生內容的多樣性。

top_p越高，產生的內容更多樣。反之更確定。

取值範圍：（0,1.0]

為了翻譯的準確性，不建議修改該值。

presence_penalty float（可選）預設值為0

控制模型產生文本時的內容重複度。

取值範圍：[-2.0, 2.0]。正值降低重複度，負值增加重複度。為了翻譯的準確性，不建議修改該值。

top_kinteger（可選）預設值為1

產生過程中採樣候選集的大小。例如，取值為50時，僅將單次產生中得分最高的50個Token組成隨機採樣的候選集。取值越大，產生的隨機性越高；取值越小，產生的確定性越高。取值為None或當top_k大於100時，表示不啟用top_k策略，此時僅有top_p策略生效。

取值需要大於或等於0。為了翻譯的準確性，不建議修改該值。

該參數非OpenAI標準參數。通過 Python SDK調用時，請放入 extra_body 對象中，配置方式為：extra_body={"top_k": xxx}；通過 Node.js SDK 或 HTTP 方式調用時，請作為頂層參數傳遞。

repetition_penaltyfloat（可選）預設值為1.05

模型產生時連續序列中的重複度。提高repetition_penalty時可以降低模型產生的重複度，1.0表示不做懲罰。取值大於0即可。為了翻譯的準確性，不建議修改該值。

該參數非OpenAI標準參數。通過 Python SDK調用時，請放入 extra_body 對象中，配置方式為：extra_body={"repetition_penalty": xxx}；通過 Node.js SDK 或 HTTP 方式調用時，請作為頂層參數傳遞。

translation_optionsobject（必選）

需配置的翻譯參數。

屬性

source_lang string （可選）

源語言的英文全稱，請參見支援的語種。若不設定，模型會自動識別輸入的語種。

target_lang string （必選）

目標語言的英文全稱，請參見支援的語種。

該參數非OpenAI標準參數。通過 Python SDK調用時，請放入 extra_body 對象中，配置方式為：extra_body={"translation_options": xxx}；通過 Node.js SDK 或 HTTP 方式調用時，請作為頂層參數傳遞。

python

import os
from openai import OpenAI

client = OpenAI(
    # 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區URL，調用時請將{WorkspaceId}替換為真實的業務空間ID，各地區的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# ----------------音頻輸入 ----------------
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",
                },
            }
        ],
    }
]

# ----------------視頻輸入(需取消注釋)----------------
# 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"
#                 },
#             }
#         ],
#     },
# ]

completion = client.chat.completions.create(
    model="qwen3-livetranslate-flash",
    messages=messages,
    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)

javascript

import OpenAI from "openai";

const client = new OpenAI({
    // 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：apiKey: "sk-xxx",
    apiKey: process.env.DASHSCOPE_API_KEY,
    // 以下為新加坡地區URL，調用時請將{WorkspaceId}替換為真實的業務空間ID，各地區的URL不同。
    baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});

// ---------------- 音頻輸入 ----------------
const 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",
                },
            },
        ],
    },
];

// ---------------- 視頻輸入(需取消注釋) ----------------
// const 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",
//                 },
//             },
//         ],
//     },
// ];

async function main() {
    const completion = await client.chat.completions.create({
        model: "qwen3-livetranslate-flash",
        messages: messages,
        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();

bash

# ======= 重要提示 =======
# 以下為新加坡地區URL，調用時請將{WorkspaceId}替換為真實的業務空間ID，各地區的URL不同。
# === 執行時請刪除該注釋 ===
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"
    }
}'

chat響應chunk對象（流式輸出）

idstring

本次調用的唯一識別碼。每個chunk對象有相同的 id。

choicesarray

模型產生內容的數組。若設定include_usage參數為true，則choices在最後一個chunk中為空白數組。

屬性

delta object

請求的增量對象。

屬性

content string

增量訊息內容。

reasoning_content string

該值固定為null。

function_call object

該值固定為null。

audioobject

輸出的音頻資訊。

屬性

data string

增量的 Base64 音頻編碼資料。

expires_at integer

建立請求時的時間戳記。

id string

輸出音訊唯一識別碼。

refusal object

該參數當前固定為null。

role string

增量訊息對象的角色，只在第一個chunk中有值。

tool_calls array

該值固定為null。

finish_reason string

模型停止產生的原因。有以下情況：

自然停止輸出時為stop；
產生未結束時為null；
產生長度過長而結束為length。

index integer

當前響應在choices數組中的索引，固定為0。

logprobsobject

該值固定為null。

createdinteger

本次請求被建立時的時間戳記。每個chunk有相同的時間戳記。

modelstring

本次請求使用的模型。

object string

始終為chat.completion.chunk。

service_tier string

該值固定為null。

system_fingerprintstring

該值固定為null。

usage object

本次請求消耗的Token。只在include_usage為true時，在最後一個chunk顯示。

屬性

completion_tokens integer

模型輸出的 Token 數。

prompt_tokens integer

輸入 Token 數。

total_tokens integer

總 Token 數，為prompt_tokens與completion_tokens的總和。

completion_tokens_details object

輸出 Token 的詳細資料。

屬性

audio_tokensinteger

輸出的音頻 Token 數。

reasoning_tokens integer

該值固定為null。

text_tokensinteger

輸出文本 Token 數。

prompt_tokens_details object

輸入 Token的細粒度分類。

屬性

audio_tokens integer

輸入音訊 Token 數。

視頻檔案中的音頻 Token 數通過本參數返回。

text_tokens integer

輸入文本的 Token 數。該值固定為0。

video_tokens integer

輸入視頻的 Token 數。

文本輸出chunk

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

音訊輸出chunk

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

Token 消耗chunk

{
  "id": "chatcmpl-c22a54b8-40cc-4a1d-988b-f84cdf86868f",
  "choices": [],
  "created": 1764755440,
  "model": "qwen3-livetranslate-flash",
  "object": "chat.completion.chunk",
  "service_tier": null,
  "system_fingerprint": null,
  "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
    }
  }
}