Qwen-Audio-ASR-Filetrans非实时语音识别Python SDK

model

str

是

模型名称。

file_urls

list[str]

是

音视频文件转写的URL列表，支持HTTP / HTTPS协议，单次请求仅支持1个URL。关于支持的音频格式、文件大小限制、时长限制等输入要求，请参见音频规格。

若录音文件存储在阿里云OSS，使用RESTful API方式支持使用以oss://为前缀的临时 URL，使用SDK方式不支持使用以 oss://为前缀的临时 URL。

parameters.keep_dialect

bool

否

仅 qwen-audio-3.1-asr-flash-filetrans 支持。默认 false，将方言转写为普通话；设为 true 时保留方言表达。完整参数说明请参见API 参考。

parameters.vocabulary_id

str

否

预编译热词列表 ID。

需预先调用创建热词列表接口生成，识别时传入该 ID 即可使用列表中的热词。

适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。

使用方法请参见预编译热词。

parameters.vocabulary

dict

否

即时热词。

以键值对形式传入，键为热词文本（string），值为热词权重（integer），无需预先创建热词列表。权重取值范围为 [1, 5] 或 50：取 [1, 5] 时值越大模型越倾向输出该词；取 50 时为超级热词，召回率大幅提升，但超级热词数量最多不超过 50 个。

适用于临时性、会话级别的热词优化。

与预编译热词同时配置时，系统会合并两类热词；合并后超过 2000 个时，随机选择 2000 个使用。使用方法请参见即时热词。

示例：

以下示例复用快速开始中已配置地域和业务空间的 client。

vocab = {"张三": 5, "李四": 5}
result = client.audio.asr.jobs.create(
    model="qwen-audio-3.1-asr-flash-filetrans",
    file_urls=["{YOUR_AUDIO_URL}"],
    parameters={"vocabulary": vocab},
)

parameters.channel_id

list[int]

否

指定在多音轨音频文件中需要识别的音轨索引，索引从 0 开始。例如，[0] 表示识别第一个音轨，[0, 1] 表示同时识别第一和第二个音轨。如果省略此参数，则默认处理第一个音轨。

默认值：[0]。

parameters.special_word_filter

str

否

指定在语音识别过程中需要处理的敏感词，并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。

parameters.diarization_enabled

bool

否

是否启用说话人分离，默认关闭。

仅适用于单声道音频，多声道音频不支持说话人分离。

启用该功能后，识别结果中将显示speaker_id字段，用于区分不同说话人。

默认值：False。

有关speaker_id的示例，请参见识别结果说明。

parameters.speaker_count

int

否

说话人数量参考值。取值范围为2至100的整数（包含2和100）。

默认自动判断说话人数量，如果配置此项，只能辅助算法尽量输出指定人数，无法保证一定会输出此人数。

无默认值。

parameters.language_hints

list[str]

否

设置待识别语言代码。如果无法提前确定语种，可不设置，模型会自动识别语种。

最多支持设置 4 个值，超出时仅前 4 个生效。

task_id

任务 ID。

status

任务状态：PENDING、RUNNING、SUCCEEDED 或 FAILED。

submitted_at

提交时间，对应 job.output["submit_time"]。

scheduled_at

开始处理时间，对应 job.output["scheduled_time"]。

finished_at

结束时间，对应 job.output["end_time"]。

output

原始任务输出字典。

results

子任务结果列表，可通过 job.results 读取；下载 transcription_url 指向的 JSON 文件可获得识别文本。

usage

任务用量信息。 qwen-audio-3.1-asr-flash-filetrans 使用 input_tokens、output_tokens 和 total_tokens 统计 Token 用量；qwen-audio-3.0-asr-flash-filetrans 按 duration 计量。

code

代表错误码。可以结合message字段，对照错误码排查问题。

message

代表错误信息。可以结合code字段，对照错误码排查问题。

task_id

任务ID。

task_status

任务状态。

有PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。

当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为SUCCEEDED，需通过subtask_status字段判断具体子任务结果。

results

子任务识别结果。

subtask_status

子任务状态。

有PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。

file_url

被识别音频的URL。

transcription_url

音频识别结果对应的URL。

识别结果以JSON格式保存在一个JSON文件中，您可以通过transcription_url对应的链接下载文件或直接通过HTTP请求读取该文件中的内容。JSON文件的内容请参见识别结果说明。

audio_format

string

源文件中音频的格式。

channels

array[integer]

源文件中音频的音轨索引信息，对单轨音频返回[0]，对双轨音频返回[0, 1]，以此类推。

original_sampling_rate

integer

源文件中音频的采样率（Hz）。

original_duration_in_milliseconds

integer

源文件中的原始音频时长（ms）。

channel_id

integer

转写结果的音轨索引，以0为起始。

content_duration

integer

音轨中被判定为语音内容的时长（ms）。

语音识别模型服务仅对音轨中被判定为语音内容的时长进行语音转写，并据此进行计量计费，非语音内容不计量、不计费。通常情况下语音内容时长会短于原始音频时长。由于对是否存在语音内容的判定是由AI模型给出的，可能与实际情况存在一定误差。

transcript

string

段落级别的语音转写结果。

sentences

array

句子级别的语音转写结果。

words

array

词级别的语音转写结果。

begin_time

integer

开始时间戳（ms）。

end_time

integer

结束时间戳（ms）。

text

string

语音转写结果。

speaker_id

integer

当前说话人的索引，以0为起始，用于区分不同的说话人。

仅在启用说话人分离功能时，该字段才会显示于识别结果中。

punctuation

string

预测出的词之后的标点符号（如有）。

transcribe

def transcribe(
    file_urls: List[str],
    *,
    model: str = "qwen-audio-3.1-asr-flash-filetrans",
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: float = 86400.0,
    submit_timeout: Optional[float] = None,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

提交任务并同步等待完成。默认模型为 qwen-audio-3.1-asr-flash-filetrans；调用其他模型时显式设置 model。

jobs.create

def create(
    *,
    model: str,
    file_urls: List[str],
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

提交任务，返回包含 task_id 和 status 的 Job，不等待识别完成。

jobs.wait

def wait(
    job: Union[Job, str],
    *,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    timeout: float = 86400.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

传入 Job 或任务 ID，同步等待任务完成。通过 poll_interval 和 max_interval 设置初始和最大轮询间隔，通过 timeout 设置总等待时间，单位均为秒。

jobs.fetch

def fetch(
    task_id: str,
    *,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

通过任务 ID 查询一次任务状态和结果，不阻塞等待任务完成。