语音识别

创建任务
查询结果

import java.nio.file.*;
import java.util.Base64;

public class Main {
  /**
   * 将 "filePath" 替换为您的音频文件路径。
   */
  public static String toDataUrl(String filePath) throws Exception {
    byte[] bytes = Files.readAllBytes(Paths.get(filePath));
    String encoded = Base64.getEncoder().encodeToString(bytes);
    return "data:audio/mpeg;base64," + encoded;
  }

  // 用法示例
  public static void main(String[] args) throws Exception {
    System.out.println(toDataUrl("input.mp3"));
  }
}

asr_options 是非标准参数。使用 OpenAI SDK 时，需通过 extra_body 传入。

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

请求体

application/json

string

必填

模型名称。仅支持 Qwen3-ASR-Flash。

object[]

必填

消息列表。

显示子属性

enum<string>

必填

消息发送者的角色。

可选值：system,user

object[]

必填

消息内容。

显示子属性

enum<string>

音频输入时设置为 input_audio。

可选值：input_audio

object

音频输入对象。

显示子属性

string

待识别的音频。支持互联网可访问文件的 URL 和 Base64 编码数据（Data URL 格式：data:<mediatype>;base64,<data>）。

string

自定义识别的上下文（仅限系统消息）。提供背景文本、实体词汇表及其他参考信息。长度限制：10,000 个 token。

object

是否启用特定功能。非标准 OpenAI 参数——使用 OpenAI SDK 时请通过 extra_body 传递。

显示子属性

enum<string>

若已知音频语言，可指定该参数以提高识别准确率。只能指定一种语言。若音频包含多种语言，请勿设置此参数。

可选值：zh,yue,en,ja,de,ko,ru,fr,pt,ar,it,es,hi,id,th,tr,uk,vi,cs,da,fil,fi,is,ms,no,pl,sv

boolean

默认值false

是否启用逆文本规范化（ITN）。仅适用于中文和英文音频。

boolean

默认值false

是否使用流式输出。建议设置为 true 以提高响应速度并降低超时风险。

object

流式输出配置。仅在 stream 为 true 时生效。

显示子属性

boolean

默认值false

是否在响应的最后一个数据块中包含 token 消耗信息。

响应

200-application/json

string

本次调用的唯一标识符。

示例:chatcmpl-487abe5f-d4f2-9363-a877-xxxxxxx

object[]

模型的输出信息。

示例:

[
  {
    "finish_reason": "stop",
    "index": 0,
    "message": {
      "annotations": [
        {
          "emotion": "neutral",
          "language": "zh",
          "type": "audio_info"
        }
      ],
      "content": "欢迎使用千问云。",
      "role": "assistant"
    }
  }
]

显示子属性

enum<string>

生成中为 null，自然结束时为 stop，超出最大长度时为 length。

可选值：stop,length,null

示例:stop

integer

choices 数组中当前对象的索引。

示例:0

object

模型输出的消息对象。

显示子属性

string

输出消息的角色，始终为 assistant。

示例:assistant

string

语音识别结果文本。

示例:欢迎使用千问云。

object[]

输出的注释信息，例如语言和情绪。

示例:

[
  {
    "emotion": "neutral",
    "language": "zh",
    "type": "audio_info"
  }
]

显示子属性

string

固定为 audio_info。

示例:audio_info

enum<string>

识别音频所用的语言。

可选值：zh,yue,en,ja,de,ko,ru,fr,pt,ar,it,es,hi,id,th,tr,uk,vi,cs,da,fil,fi,is,ms,no,pl,sv

示例:zh

enum<string>

识别音频中的情绪。

可选值：surprised,neutral,happy,sad,disgusted,angry,fearful

示例:neutral

integer

请求创建时的 UNIX 时间戳（秒）。

示例:1767683986

string

本次请求使用的模型。

示例:qwen3-asr-flash

string

始终为 chat.completion。

示例:chat.completion

object

Token 消耗信息。

显示子属性

integer

模型输出的 token 数量。

示例:12

object

显示子属性

integer

模型输出文本的 token 数量。

示例:12

integer

输入的 token 数量。

示例:42

object

显示子属性

integer

输入音频的 token 长度。每秒音频折算为 25 个 token，不足 1 秒按 1 秒计算。

示例:42

integer

忽略此参数。

示例:0

integer

音频时长（秒）。

示例:1

integer

输入和输出的 token 总量。

示例:54

from openai import OpenAI
import os

try:
  client = OpenAI(
    # 如果您尚未配置环境变量，请将以下代码行替换为您的 API Key：api_key = "sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
  )
  

  stream_enabled = False  # 是否启用流式输出
  completion = client.chat.completions.create(
    model="qwen3-asr-flash",
    messages=[
      {
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
            }
          }
        ],
        "role": "user"
      }
    ],
    stream=stream_enabled,
    # 当 stream 设置为 False 时，不能设置 stream_options 参数
    # stream_options={"include_usage": True},
    extra_body={
      "asr_options": {
        # "language": "zh",
        "enable_itn": False
      }
    }
  )
  if stream_enabled:
    full_content = ""
    print("流式输出内容为：")
    for chunk in completion:
      # 若 stream_options.include_usage 为 True，最后一个 chunk 的 choices 字段为空列表，应跳过（可通过 chunk.usage 获取 token 用量）
      print(chunk)
      if chunk.choices and chunk.choices[0].delta.content:
        full_content += chunk.choices[0].delta.content
    print(f"完整内容为：{full_content}")
  else:
    print(f"非流式输出内容为：{completion.choices[0].message.content}")
except Exception as e:
  print(f"错误信息：{e}")

{
  "id": "chatcmpl-487abe5f-d4f2-9363-a877-xxxxxxx",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "annotations": [
          {
            "emotion": "neutral",
            "language": "zh",
            "type": "audio_info"
          }
        ],
        "content": "欢迎使用千问云。",
        "role": "assistant"
      }
    }
  ],
  "created": 1767683986,
  "model": "qwen3-asr-flash",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 12,
    "completion_tokens_details": {
      "text_tokens": 12
    },
    "prompt_tokens": 42,
    "prompt_tokens_details": {
      "audio_tokens": 42,
      "text_tokens": 0
    },
    "seconds": 1,
    "total_tokens": 54
  }
}

非实时

录音文件识别最佳实践

使用 ffmpeg 对视频文件进行预处理，提取音轨并压缩，从而加快 Paraformer 录音文件识别的吞吐效率。

虽然 Paraformer 语音识别 API 可以兼容视频文件，但由于视频文件尺寸通常较大、传输较为耗时，建议对其进行预处理，仅提取需要进行语音识别的音轨，并进行合理压缩，从而显著降低文件尺寸。这样做将大大加快视频文件转写的吞吐效率。以下展示了如何使用 ffmpeg 进行相关预处理。

前提条件

安装 ffmpeg：请前往 ffmpeg 官方网站下载并安装。

预处理视频文件

使用 ffmpeg 提取视频文件中的第一条音轨、降采样到 16kHz、并压缩编码为 opus 文件。

ffmpeg -i input-video-file -ac 1 -ar 16000 -acodec libopus output-audio-file.opus

一般情况下，输出的音频文件将显著小于输入视频文件的尺寸。之后可向文件转写 API 提交该音频文件（以 URL 指定），获得语音识别结果。

本页目录

前提条件
预处理视频文件