语音转写模型接入指南

概述

本文档介绍如何通过 API 使用 SiliEvo 平台的语音转写（Automatic Speech Recognition, ASR）服务，将录音文件转换为文字。适用于会议转写、通话分析、字幕生成、语音助手等场景。

平台提供同步与异步两种转写方式：

同步转写：短音频（≤5 分钟）秒级返回识别结果，请求直接返回转写文本。

异步转写：长音频（可数小时）通过「提交任务 → 轮询查询 → 获取结果」三步完成，适合会议录音、访谈等长音频。

前提条件

请牢记 SiliEvo 中转服务的核心两要素：

中转基地址 (Base URL): https://api.numspirit.com/

安全秘钥 (API Key / Token): 通过平台官网 https://numspirit.com 或联系 15685255305 申请，形如 sk-silievo-xxxxxxxx

注：如使用其他部署环境（如国内 www.silievo.com），基地址以实际分配为准，/v1/audio/transcriptions 路径不变。

支持的模型

模型	类型	说明
`qwen3-asr-flash`	同步	通义千问 Qwen3-ASR-Flash，适合 ≤5 分钟短音频，请求直接返回文字，延迟低
`qwen3-asr-flash-filetrans`	异步	Qwen3-ASR-Flash 录音文件转写，适合长音频（最长 12 小时），任务完成一次性返回全部结果

如何选择：

音频 ≤ 5 分钟、10MB 以内、想快速拿到结果 → 用同步模型 qwen3-asr-flash。

音频较长（> 5 分钟，会议/访谈/课程录音）→ 用异步模型 qwen3-asr-flash-filetrans。

提示：调用时 model 需写全渠道前缀，如 aliyun_asr/qwen3-asr-flash、aliyun_asr/qwen3-asr-flash-filetrans，平台按渠道前缀路由到对应渠道。下文所有示例均使用此写法。

接口总览

接口	方法	Content-Type	说明
`/v1/audio/transcriptions`	POST	`multipart/form-data`	转写：`model`(必填) + `file` 或 `url` 二选一 + `language`(可选)。同步模型直接返回 `{"text":...}`；异步模型返回任务 ID
`/v1/audio/transcriptions/{taskId}`	GET	—	异步任务查询（读本地库，不实时调上游），返回任务状态与结果

请求 Header

所有请求都需要在 HTTP Header 中携带认证信息：

Content-Type: multipart/form-data   (POST)
Authorization: Bearer sk-silievo-xxxxxxxx

一、同步转写（qwen3-asr-flash）

接口信息

属性	说明
接口地址	`POST https://api.numspirit.com/v1/audio/transcriptions`
模型	`aliyun_asr/qwen3-asr-flash`
音频限制	时长 ≤ 5 分钟（300 秒），大小 ≤ 10MB
支持格式	`wav`、`mp3`、`aac`、`ogg`、`flac`、`m4a`
计费模式	按音频时长计费（元/秒）

请求参数（multipart/form-data）

字段	类型	必填	说明
`model`	string	是	模型名称，固定为 `aliyun_asr/qwen3-asr-flash`
`file`	file	二选一	音频文件（`file` 与 `url` 只能传一个，不能都传）
`url`	string	二选一	音频文件的公网可访问地址（平台会下载后转写，计费口径与 `file` 一致）
`language`	string	否	音频语种提示，如 `zh`、`en`。不传时自动检测

响应示例

{
    "text": "今天天气太棒了，我该去哪里玩呢？"
}

响应字段说明：

字段	类型	说明
`text`	string	转写出的完整文本

cURL 示例

方式一：本地上传文件

方式二：传音频公网 URL

方式三：指定语种

若文件不是 wav（mp3/flac/ogg/m4a），把 type=audio/mpeg（mp3）、audio/flac、audio/ogg、audio/x-m4a 换成对应 MIME 即可；不传 type 或传 application/octet-stream 时，平台会自动按文件魔数识别格式。

二、异步转写（qwen3-asr-flash-filetrans）

异步转写分三步：① 提交任务 → ② 轮询查询状态 → ③ 状态为 SUCCEEDED 时读取转写文本。

接口信息

属性	说明
提交地址	`POST https://api.numspirit.com/v1/audio/transcriptions`
查询地址	`GET https://api.numspirit.com/v1/audio/transcriptions/{taskId}`
模型	`aliyun_asr/qwen3-asr-flash-filetrans`
音频限制	大小 ≤ 200MB（平台网关限制；阿里云原生支持最长 12 小时 / 2GB）
支持格式	`wav`、`mp3`、`aac`、`ogg`、`flac`、`m4a`
计费模式	按音频时长计费（元/秒）

2.1 提交任务

请求参数与同步相同：model(必填) + file 或 url 二选一 + language(可选)。

cURL 提交示例

提交成功响应

{
    "id": "task-3f2a9c01-8b4e-4d6e-9c7f-1a2b3c4d5e6f",
    "object": "audio.transcription",
    "created": 1783659200,
    "model": "aliyun_asr/qwen3-asr-flash-filetrans",
    "status": "PENDING"
}

响应字段说明：

字段	类型	说明
`id`	string	任务 ID，后续查询用它
`object`	string	固定为 `audio.transcription`
`created`	integer	任务创建时间（Unix 时间戳）
`model`	string	使用的模型
`status`	string	初始为 `PENDING`（排队中）

2.2 查询任务状态

cURL 查询示例

状态流转

任务状态依次为：PENDING（排队）→ PROCESSING（转写中）→ SUCCEEDED（成功，此时返回转写文本）；失败时为 FAILED（上游错误）或 TIMEOUT（超时）。

成功响应（SUCCEEDED）

{
    "id": "task-3f2a9c01-8b4e-4d6e-9c7f-1a2b3c4d5e6f",
    "object": "audio.transcription",
    "created": 1783659200,
    "model": "aliyun_asr/qwen3-asr-flash-filetrans",
    "status": "SUCCEEDED",
    "duration": 3720,
    "text": "各位同事下午好，今天我们会议的主题是……"
}

响应字段说明：

字段	类型	说明
`status`	string	`SUCCEEDED` 表示转写完成
`duration`	integer	音频时长（秒），也是本次计费的时长
`text`	string	转写全文（仅 `SUCCEEDED` 时有）
`error`	object	失败时返回，含 `code` 与 `message`

失败响应示例（FAILED / TIMEOUT）

{
    "id": "task-3f2a9c01-8b4e-4d6e-9c7f-1a2b3c4d5e6f",
    "object": "audio.transcription",
    "created": 1783659200,
    "model": "aliyun_asr/qwen3-asr-flash-filetrans",
    "status": "FAILED",
    "duration": 3720,
    "error": {
        "code": "PROVIDER_ERROR",
        "message": "上游转写任务失败"
    }
}

2.3 轮询示例（Bash）

错误码速查表

错误码	HTTP 状态码	说明	解决方案
`auth_error`	401	认证失败，API Key 无效或未提供	检查 `Authorization` Header 格式与 Key 是否有效
`quota_exceeded` / `balance_insufficient`	402	余额不足或额度已用尽	充值或联系客服
`invalid_request`	400	请求参数错误（缺 model、file/url 都传或都缺、格式不支持、超大小/时长上限、URL 下载失败）	按返回的 `message` 检查请求
`model_not_supported`	400	模型不存在或不受支持	检查 `model` 参数拼写
`price_not_configured`	400	该模型未配置价格	联系平台管理员配置价格
`task_not_found`	404	任务不存在（或非本人任务，伪装为不存在）	检查 `taskId`；异步任务仅本人可查
`provider_error` / `channel_token_exhausted`	502	上游服务异常或渠道 Token 耗尽	稍后重试或联系客服
`service_unavailable`	503	模型未配置有效渠道	联系平台管理员

注意事项

同步与异步选择：≤5 分钟、10MB 以内的短音频用 qwen3-asr-flash；长音频用 qwen3-asr-flash-filetrans。同步模型超过 300 秒或 10MB 会被拒绝并提示改用异步模型。

支持格式：仅支持 wav、mp3、aac、ogg、flac、m4a。文件过大可用 ffmpeg 转码或裁剪后再传。

计费方式：按音频实际时长计费（元/秒 × 秒数）。duration 为服务端解析的计费时长，可在异步查询结果中直接看到；同步转写以实际扣费日志为准。具体单价以平台展示为准。

异步任务归属：任务仅允许提交方本人查询，用其他 Key 查询他人任务会返回 404（防泄漏）。

URL 输入：传 url 时该地址必须公网可访问；下载失败会返回 400，可改用 file 上传。

结果保存：异步任务 SUCCEEDED 后 text 即最终结果，请及时保存。

技术支持: 如有任何问题，请联系客服微信或加入服务群获取帮助。

语音转录接口

语音转写模型接入指南#

概述#

前提条件#

支持的模型#

接口总览#

请求 Header#

一、同步转写（qwen3-asr-flash）#

接口信息#

请求参数（multipart/form-data）#

响应示例#

cURL 示例#

二、异步转写（qwen3-asr-flash-filetrans）#

接口信息#

2.1 提交任务#

cURL 提交示例#

提交成功响应#

2.2 查询任务状态#

cURL 查询示例#

状态流转#

成功响应（SUCCEEDED）#

失败响应示例（FAILED / TIMEOUT）#

2.3 轮询示例（Bash）#

错误码速查表#

注意事项#

语音转写模型接入指南

概述

前提条件

支持的模型

接口总览

请求 Header

一、同步转写（qwen3-asr-flash）

接口信息

请求参数（multipart/form-data）

响应示例

cURL 示例

二、异步转写（qwen3-asr-flash-filetrans）

接口信息

2.1 提交任务

cURL 提交示例

提交成功响应

2.2 查询任务状态

cURL 查询示例

状态流转

成功响应（SUCCEEDED）

失败响应示例（FAILED / TIMEOUT）

2.3 轮询示例（Bash）

错误码速查表

注意事项