转录

异步音视频转录（音视频转文字），支持自动识别说话人。

计费：按实际音频时长，每开始一分钟 4 个 API 积分。确认实际时长后、开始转录前预扣积分，转录失败自动退回。文件处理期间尚未取得时长时不扣积分。

创建任务前会检查是否至少有 4 个 API 积分。不足时返回 HTTP 402 和 code: "insufficient_credits"，不创建任务、不扣积分。通过最低余额预检，不代表余额一定足够支付完整转录费用。

接口：POST/transcriptions GET/transcriptions/{id}

提交任务

传入公网可访问的音频或视频文件地址，可以来自 SnapAny 提取接口，也可以使用你自备的地址：

curl -X POST https://api.snapany.com/openapi/v1/transcriptions \
  -H "Authorization: Bearer sk_snapany_xxx" \
  -H "Accept-Language: zh" \
  -H "Content-Type: application/json" \
  -d '{"fileUrl": "https://example.com/audio.mp3", "speakerLabels": true}'

或上传本地文件（最大 512 MiB）：

curl -X POST https://api.snapany.com/openapi/v1/transcriptions \
  -H "Authorization: Bearer sk_snapany_xxx" \
  -H "Accept-Language: zh" \
  -F "file=@meeting.mp3" -F "speakerLabels=true"

提交成功后立即返回 { "id": "...", "status": "processing" }。文件处理和转录会继续执行，使用这个 id 查询结果即可。

language — 英文语种名或 ISO-639-1 代码（如 english、en）。省略该字段即自动检测，不存在 "auto" 这个取值。 zh-CN 这类区域子标签会被 unsupported_language 拒绝，请改用主语言代码。

文件地址与下载请求头

音频地址和视频文件地址都支持，公网 HTTP/HTTPS 域名及公有 IP 均可使用；回环、内网和其他特殊地址会被拒绝。如果有独立音频地址，可以直接提交音频。文件最大 512 MiB，不限制时长。

JSON URL 请求还支持：

{
  "fileUrl": "https://example.com/video.mp4",
  "fileHeaders": { "Referer": "https://example.com/" },
  "speakerLabels": true
}

每次提交都会创建独立任务，即使文件地址相同也会分别计费。查看已有任务时，请查询它的 id，不要重新提交。

说话人识别

设置 speakerLabels: true 后自动识别说话人和人数，无需指定人数。

参数变更：maxSpeakers 已废弃。旧 JSON、multipart 和 MCP 请求仍可携带该字段，但其值会被忽略，不再限制人数；其他参数校验保持不变。

轮询结果

curl https://api.snapany.com/openapi/v1/transcriptions/{id} \
  -H "Authorization: Bearer sk_snapany_xxx" \
  -H "Accept-Language: zh"

每 3–5 秒轮询一次（轮询免费）。文件处理期间，status 为 processing，duration 为 null：

{
  "id": "...",
  "status": "processing",
  "duration": null,
  "errorCode": null,
  "error": null
}

取得实际音频时长后，duration 为以秒为单位的数值。视频没有音轨或文件下载失败时，任务会变为 failed，不扣积分。已经通过最低余额预检的任务，如果确认实际时长后余额不足以支付完整费用，也会变为 failed，并返回 errorCode: "insufficient_credits"，不扣积分。通过同一查询读取程序可识别的 errorCode 和可向用户展示的 error：

{
  "id": "...",
  "status": "failed",
  "duration": null,
  "errorCode": "audio_track_missing",
  "error": "视频中没有音轨"
}

常见错误码包括 audio_track_missing、download_failed、download_timeout 和 insufficient_credits。如果已经预扣积分后转录失败，积分会自动退回。

轮询循环示例：

import time
import requests

headers = {"Authorization": f"Bearer {API_KEY}"}
url = f"https://api.snapany.com/openapi/v1/transcriptions/{job_id}"

while True:
    job = requests.get(url, headers=headers).json()
    if job["status"] == "completed":
        print(job["result"]["text"])
        break
    if job["status"] == "failed":
        print("失败：", job["errorCode"], job["error"])
        break
    time.sleep(5)

status 为 completed 时，result 是与 verbose_json 兼容的转录结果：完整 text、检测到的 language、带起止时间戳的 segments——开启说话人分离时每段带 speaker 标签。