语音转文字 API · 调用文档

上传音频或提交公网音频链接，创建异步转写任务并查询完整文本、句子列表和扣费结果。

语音转文字 API 用于把会议、访谈、课程、播客和短视频音频转成可继续写入表格、知识库或自动化流程的文本。

转写任务为异步调用。提交任务后轮询状态，转写成功并交付结果后才扣积分；上传、参数错误、鉴权失败、余额不足或转写失败都不扣。

三步开始

注册：打开 /sign-up 注册，注册即送体验积分。
创建 API Key：到 /settings/apikeys 创建，形如 sk-xxxxxxxx。
准备音频：本地音频先上传；已有公网 HTTP/HTTPS 音频链接时可以直接创建任务。

API Key 等于账户凭证，不要外泄或提交到代码仓库。泄露后请立即删除并重建。

当前价格

产品码	说明	积分
`asr_minute`	语音转文字云端档	4

按向上取整的分钟数计费。例如 61 秒按 2 分钟计费，扣 8 积分。上传音频不扣费，重复查询同一任务不会重复扣费。

1. 上传本地音频

已有可访问的公网音频链接时可以跳过此步。上传接口支持常见音频和视频音轨文件，单文件默认不超过 200MB。

curl -X POST 'https://firefly.qwjxqn.xyz/v1/asr/upload' \
  -H 'X-API-Key: sk-你的key' \
  -H 'Content-Type: audio/mpeg' \
  --data-binary '@./meeting.mp3'

成功返回 Firefly 音频链接：

{
  "code": 0,
  "msg": "成功",
  "request_id": "asr-upload-...",
  "data": {
    "audio_url": "https://firefly.qwjxqn.xyz/media/asr_upload_....mp3",
    "bytes": 5242880,
    "content_type": "audio/mpeg"
  }
}

也可以用 Authorization: Bearer sk-你的key 代替 X-API-Key。

2. 创建转写任务

把上传返回的 audio_url，或你自己的公网音频链接，提交到任务接口。

curl -X POST 'https://firefly.qwjxqn.xyz/v1/asr/tasks' \
  -H 'X-API-Key: sk-你的key' \
  -H 'Idempotency-Key: asr-20260729-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "audio_url": "https://firefly.qwjxqn.xyz/media/asr_upload_....mp3",
    "duration_seconds": 183
  }'

成功提交返回 HTTP 202：

{
  "code": 0,
  "msg": "成功",
  "request_id": "asr-...",
  "data": {
    "task_id": "8dd91b4e-...",
    "status": "processing",
    "product_code": "asr_minute",
    "audio_url": "https://firefly.qwjxqn.xyz/media/asr_upload_....mp3",
    "duration_seconds": 183,
    "estimated_minutes": 4,
    "credits_price": 16,
    "credits_charged": 0
  }
}

请求参数

参数	必填	说明
`audio_url`	是	Firefly 上传链接或公网 HTTP/HTTPS 音频链接
`duration_seconds`	否	音频时长秒数；传入后可提前估算扣费

建议每次提交携带唯一的 Idempotency-Key。网络重试时复用同一个值，避免重复创建任务。

外部链接必须能被 Firefly 服务端访问。localhost、内网地址和私有 IP 会被拒绝。

3. 查询转写结果

curl 'https://firefly.qwjxqn.xyz/v1/asr/tasks/8dd91b4e-...' \
  -H 'X-API-Key: sk-你的key'

处理中返回：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "task_id": "8dd91b4e-...",
    "status": "processing",
    "credits_charged": 0
  }
}

成功后返回：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "task_id": "8dd91b4e-...",
    "status": "succeeded",
    "product_code": "asr_minute",
    "duration_seconds": 183,
    "billable_minutes": 4,
    "credits_price": 16,
    "credits_charged": 16,
    "balance": 984,
    "transcript": {
      "full_text": "今天我们讨论三个问题...",
      "sentences": [
        {
          "start_ms": 0,
          "end_ms": 4820,
          "text": "今天我们讨论三个问题。"
        }
      ]
    }
  }
}

credits_charged 只在本次查询实际完成扣费时显示本次扣费；后续重复查询同一任务为 0，不会再次扣费。

常见状态码

HTTP	含义	是否扣费
`400`	参数错误、音频链接无效或文件过大	否
`401`	API Key 缺失或无效	否
`402`	余额不足	否
`404`	任务不存在，或任务不属于当前账户	否
`429`	请求过快	否
`502`	转写服务暂时失败	否
`503`	Firefly 计费或存储暂时不可用	否
`504`	转写任务超时	否

接入建议

长音频通常需要几十秒到数分钟，请轮询任务接口，不要把提交请求当作同步转写。
每 3–5 秒查询一次即可，不要高频轮询。
如果音频在你自己的对象存储里，确认链接没有登录态、没有防盗链、没有很短的过期时间。
建议传入 duration_seconds，便于调用前做余额预估；实际扣费仍以成功任务的可计费分钟数为准。
字段捷径或表格自动化中，建议保存 task_id、status、full_text、credits_charged 和 balance，方便重试和对账。

语音转文字 API · 调用文档

On this page