音视频文件翻译-千问

工作方式

设置语种：参考支持的语种，在 translation_options 参数中设置源语种 (source_lang) 和目标语种 (target_lang)。
省略 source_lang将启用自动检测，但指定语种能提升翻译准确率。
输入待翻译文件：messages 数组中有且仅有一条 role 为 user 的消息，content字段需传入待翻译音频/视频的 URL 或 Base64 数据。
**控制输出模态：**通过 modalities 参数控制输出模态：
- ["text"]：仅输出文本；
- ["text","audio"]：输出文本和 Base64 编码的音频。
  若输出音频，需在audio参数中设置音色（voice）。参考支持的音色。

以下为使用 OpenAI Python SDK 的核心代码：

# 导入依赖与创建客户端...
completion = client.chat.completions.create(
    model="qwen3-livetranslate-flash",    # 选择模型
    # messages 仅包含一条 user 消息，content 为待翻译文件
    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"
          }
        }
      ]
    }
  ],
    # translation_options 非 OpenAI 标准参数，需通过 extra_body 传入
    extra_body={"translation_options": {"source_lang": "zh", "target_lang": "en"}},
    # 示例：输出文本和音频
    modalities = ["text","audio"],
    audio={"voice": "Cherry", "format": "wav"},
    stream=True
)

使用限制

单轮翻译：模型专为翻译任务设计，不支持多轮对话。
无 System Message：不支持通过 system 角色设定全局行为。
**调用方式：**仅支持兼容 OpenAI 协议的流式输出。

响应解析 chunk为流式响应对象：

文本：读取 chunk.choices[0].delta.content。
音频：读取 chunk.choices[0].delta.audio["data"]，模型输出音频的采样率是 24kHz。

支持的模型

模型名称	版本	上下文长度	最大输入	最大输出
模型名称	版本	（Token数）
qwen3-livetranslate-flash 当前能力等同于qwen3-livetranslate-flash-2025-12-01	稳定版	53,248	49,152	4,096
qwen3-livetranslate-flash-2025-12-01	快照版	53,248	49,152	4,096

如何使用

qwen3-livetranslate-flash 模型支持音频或视频输入，并输出文本与音频。请确保已获取与配置 API Key并配置API Key到环境变量。若通过OpenAI SDK调用，需安装SDK。以下示例使用音频输入。如需输入视频，请取消对应代码的注释。

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量，请用千问AI平台API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qianwenaiapi.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)

此示例使用公网文件 URL。若使用本地文件，请参见输入 Base64 编码的本地文件中的音频与视频部分。

解析 Base64 音频数据

模型以流式 Base64 编码格式输出音频。可采用以下两种方式处理数据：

**拼接解码：**拼接所有返回的 Base64 片段，待生成结束后统一解码，保存为音频文件。
**实时播放：**实时解码每个 Base64 片段并直接播放。

# Installation instructions for pyaudio:
# APPLE Mac OS X
#   brew install portaudio
#   pip install pyaudio
# Debian/Ubuntu
#   sudo apt-get install python-pyaudio python3-pyaudio
#   or
#   pip install pyaudio
# CentOS
#   sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Microsoft Windows
#   python -m pip install pyaudio

import os
from openai import OpenAI
import base64
import numpy as np
import soundfile as sf

# 初始化OpenAI客户端
client = OpenAI(
    # 若没有配置环境变量，请用千问AI平台API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qianwenaiapi.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",
                },
            }
        ],
    }
]
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"}},
)

# 方式1: 待生成结束后再进行解码
audio_string = ""
for chunk in completion:
    if chunk.choices:
        if hasattr(chunk.choices[0].delta, "audio"):
            try:
                audio_string += chunk.choices[0].delta.audio["data"]
            except Exception as e:
                print(chunk.choices[0].delta.audio["transcript"])
    else:
        print(chunk.usage)

wav_bytes = base64.b64decode(audio_string)
audio_np = np.frombuffer(wav_bytes, dtype=np.int16)
sf.write("audio_assistant_py.wav", audio_np, samplerate=24000)

# 方式2: 边生成边解码(使用方式2请将方式1的代码进行注释)
# # 初始化 PyAudio
# import pyaudio
# import time
# p = pyaudio.PyAudio()
# # 创建音频流
# stream = p.open(format=pyaudio.paInt16,
#                 channels=1,
#                 rate=24000,
#                 output=True)

# for chunk in completion:
#     if chunk.choices:
#         if hasattr(chunk.choices[0].delta, "audio"):
#             try:
#                 audio_string = chunk.choices[0].delta.audio["data"]
#                 wav_bytes = base64.b64decode(audio_string)
#                 audio_np = np.frombuffer(wav_bytes, dtype=np.int16)
#                 # 直接播放音频数据
#                 stream.write(audio_np.tobytes())
#             except Exception as e:
#                 print(chunk.choices[0].delta.audio["transcript"])

# time.sleep(0.8)
# # 清理资源
# stream.stop_stream()
# stream.close()
# p.terminate()

计费说明

音频
视频

输入或输出每秒音频均消耗 12.5 Token。

视频文件的 Token 分为 video_tokens（视觉）与 audio_tokens（音频）。

video_tokens 本脚本用于计算 video_tokens。计算流程如下：
1. 帧数采样：以 2 FPS 速率采样。将帧数限制在 [4, 128] 之间。
2. 尺寸调整：将高与宽调整为 32 的倍数。根据帧数动态缩放，适配总像素限制。
3. Token 计算：⌈帧数/2⌉ × (高/32) × (宽/32) + 2。

# 使用前安装：pip install opencv-python
import math
import os
import cv2

# 固定参数
FRAME_FACTOR = 2

IMAGE_FACTOR = 32

# 视频帧的长宽比
MAX_RATIO = 200

# 视频帧的像素下限
VIDEO_MIN_PIXELS = 128 * 32 * 32

# 视频帧的像素上限
VIDEO_MAX_PIXELS = 768 * 32 * 32

FPS = 2
# 最少抽取帧数
FPS_MIN_FRAMES = 4

# 最大抽取帧数
FPS_MAX_FRAMES = 128

# 视频输入的最大像素值，
VIDEO_TOTAL_PIXELS = 16384 * 32 * 32

def round_by_factor(number, factor):
    return round(number / factor) * factor

def ceil_by_factor(number, factor):
    return math.ceil(number / factor) * factor

def floor_by_factor(number, factor):
    return math.floor(number / factor) * factor

def get_video(video_path):
    cap = cv2.VideoCapture(video_path)
    frame_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
    frame_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
    video_fps = cap.get(cv2.CAP_PROP_FPS)
    cap.release()
    return frame_height, frame_width, total_frames, video_fps

def smart_nframes(total_frames, video_fps):
    min_frames = ceil_by_factor(FPS_MIN_FRAMES, FRAME_FACTOR)
    max_frames = floor_by_factor(min(FPS_MAX_FRAMES, total_frames), FRAME_FACTOR)
    duration = total_frames / video_fps if video_fps != 0 else 0
    if duration - int(duration) > (1 / FPS):
        total_frames = math.ceil(duration * video_fps)
    else:
        total_frames = math.ceil(int(duration) * video_fps)
    nframes = total_frames / video_fps * FPS
    nframes = int(min(min(max(nframes, min_frames), max_frames), total_frames))
    if not (FRAME_FACTOR <= nframes <= total_frames):
        raise ValueError(f"nframes should in interval [{FRAME_FACTOR}, {total_frames}], but got {nframes}.")
    return nframes

def smart_resize(height, width, nframes, factor=IMAGE_FACTOR):
    min_pixels = VIDEO_MIN_PIXELS
    total_pixels = VIDEO_TOTAL_PIXELS
    max_pixels = max(min(VIDEO_MAX_PIXELS, total_pixels / nframes * FRAME_FACTOR), int(min_pixels * 1.05))
    if max(height, width) / min(height, width) > MAX_RATIO:
        raise ValueError(f"absolute aspect ratio must be smaller than {MAX_RATIO}, got {max(height, width) / min(height, width)}")
    h_bar = max(factor, round_by_factor(height, factor))
    w_bar = max(factor, round_by_factor(width, factor))
    if h_bar * w_bar > max_pixels:
        beta = math.sqrt((height * width) / max_pixels)
        h_bar = floor_by_factor(height / beta, factor)
        w_bar = floor_by_factor(width / beta, factor)
    elif h_bar * w_bar < min_pixels:
        beta = math.sqrt(min_pixels / (height * width))
        h_bar = ceil_by_factor(height * beta, factor)
        w_bar = ceil_by_factor(width * beta, factor)
    return h_bar, w_bar

def video_token_calculate(video_path):
    height, width, total_frames, video_fps = get_video(video_path)
    nframes = smart_nframes(total_frames, video_fps)
    resized_height, resized_width = smart_resize(height, width, nframes)
    video_token = int(math.ceil(nframes / FPS) * resized_height / 32 * resized_width / 32)
    video_token += 2  # 视觉标记
    return video_token

if __name__ == "__main__":
    video_path = "spring_mountain.mp4"  # 你的视频路径
    video_token = video_token_calculate(video_path)
    print("video_tokens:", video_token)

audio_tokens 每秒音频消耗 12.5 Token。若音频时长不足1秒，按 1 秒计算。

Token 费用请参见选择模型。

API 参考

qwen3-livetranslate-flash 模型的输入输出参数请参见音视频翻译-通义千问。

支持的语种

下表中的语种代码可用于指定源语种与目标语种。

部分目标语种仅支持输出文本，不支持输出音频。

语种代码	语种	支持的输出模态
en	英语	音频、文本
zh	中文	音频、文本
ru	俄语	音频、文本
fr	法语	音频、文本
de	德语	音频、文本
pt	葡萄牙语	音频、文本
es	西班牙语	音频、文本
it	意大利语	音频、文本
id	印尼语	文本
ko	韩语	音频、文本
ja	日语	音频、文本
vi	越南语	文本
th	泰语	文本
ar	阿拉伯语	文本
yue	粤语	音频、文本
hi	印地语	文本
el	希腊语	文本
tr	土耳其语	文本

支持的音色

音色名	`voice`参数	描述	支持的语种
芊悦	Cherry	阳光积极、亲切自然小姐姐。	中文、英语、法语、德语、俄语、意大利语、西班牙语、葡萄牙语、日语、韩语
不吃鱼	Nofish	不会翘舌音的设计师。	中文、英语、法语、德语、俄语、意大利语、西班牙语、葡萄牙语、日语、韩语
上海-阿珍	Jada	风风火火的沪上阿姐。	中文
北京-晓东	Dylan	北京胡同里长大的少年。	中文
四川-晴儿	Sunny	甜到你心里的川妹子。	中文
天津-李彼得	Peter	天津相声，专业捧人。	中文
粤语-阿清	Kiki	甜美的港妹闺蜜。	粤语
四川-程川	Eric	一个跳脱市井的四川成都男子。	中文

常见问题

Q：传入视频文件时，翻译的是什么内容？

A：翻译视频中的音频内容，视觉信息用于辅助上下文理解，以提升准确率。示例：当音频内容为This is a mask时：

若画面显示口罩，会翻译为“这是一个口罩”；
若画面显示面具，会翻译为“这是一个面具”。

​工作方式

​支持的模型

​如何使用

​解析 Base64 音频数据

​计费说明

​API 参考

​支持的语种

​支持的音色

​常见问题

​Q：传入视频文件时，翻译的是什么内容？