文件上传
本地音频先申请上传,需要时按返回的地址与请求头上传文件,再用 uploadId 创建转录任务。
目前只接受音频,最大 1 GiB(1,073,741,824 字节)。本地视频请先提取音轨;已有音频或视频文件地址时,也可以直接通过 fileUrl 转录。
1. 申请上传
POST/uploads申请免费,但要求 API 积分余额大于 0。鉴权沿用转录使用的 API Key。
curl -X POST https://api.snapany.com/openapi/v1/uploads \
-H "Authorization: Bearer sk_snapany_xxx" \
-H "Accept-Language: zh" \
-H "Content-Type: application/json" \
-d '{"mediaType":"audio","sizeBytes":12345678,"sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}'
| 参数 | 必填 | 说明 |
|---|---|---|
mediaType | 是 | 固定为 "audio" |
sizeBytes | 是 | 原文件精确字节数,范围 1 至 1,073,741,824 |
sha256 | 是 | 完整原始文件的 SHA-256,64 位十六进制,大小写均可 |
摘要应从原文件字节计算,不能对文件名或 base64 文本计算。取得大小和摘要后不要再修改文件。请求中的未知字段会被拒绝。
需要 PUT 时,响应为:
{
"uploadId": "abcdefghijklmnopqrstuvwx",
"upload": {
"method": "PUT",
"url": "https://storage.example.com/signed-upload-url",
"headers": {
"Content-Type": "application/octet-stream"
},
"expiresAt": "2026-11-09T12:00:00.000Z"
}
}
请求头仅作示例,上传时必须原样使用实际返回的全部 upload.headers,包括存在时的校验头。expiresAt 是 UTC ISO 时间,签名地址有效期最长一小时。
如果服务端确认本账号可复用相同内容,会返回 { "uploadId": "...", "upload": null }。只有 upload: null 才表示跳过 PUT,不能仅凭本地摘要相同就认为文件已经可用。
2. PUT 原始音频字节
upload 不为 null 时,按返回的请求头将完整原文件 PUT 到 upload.url。PUT 上传时不要携带 SnapAny API Key,请求正文直接使用文件字节,不附加表单字段,也不使用 base64 编码。
签名地址的域名、路径和查询参数都保持原样,不要替换成 api.snapany.com 或 api-cn.snapany.com;上传时也不要跟随重定向。PUT 成功返回 2xx,无需再调用单独的完成接口。
单次 PUT 不支持从中间断点续传。失败后在地址有效期内重新传完整文件;地址过期后重新申请,响应会说明是否可以跳过 PUT。签名地址到期不会立即删除已上传文件。uploadId 只是该上传的临时使用资格,不是永久文件 ID,失去使用资格后需要重新申请。
3. 用 uploadId 提交转录
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 '{"uploadId":"abcdefghijklmnopqrstuvwx","speakerLabels":false}'
响应中的 id 是独立的转录任务 ID,每 3–5 秒查询一次。文件校验在后台继续;校验失败,或确认实际时长后余额不足时,任务失败,不启动付费转录。直传本身不扣积分;转录不识别说话人每分钟 3 个 API 积分,识别说话人为 4 个。
uploadId 归属于账号,同一账号的其他 API Key 也可以使用。它可以用于多个单独计费的任务,例如选择不同语言或说话人设置,不具备创建任务幂等语义。不要同时提交 fileUrl 或 fileHeaders。
Python 示例
在环境变量中设置 SNAPANY_API_KEY,并安装 requests。以下示例计算 meeting.mp3 的摘要、直传文件,再提交一次转录:
import hashlib
import os
from pathlib import Path
import requests
base_url = "https://api.snapany.com/openapi/v1"
api_headers = {"Authorization": f"Bearer {os.environ['SNAPANY_API_KEY']}"}
file_path = Path("meeting.mp3")
sha256 = hashlib.sha256()
with file_path.open("rb") as audio:
for chunk in iter(lambda: audio.read(1024 * 1024), b""):
sha256.update(chunk)
response = requests.post(
f"{base_url}/uploads",
headers=api_headers,
json={
"mediaType": "audio",
"sizeBytes": file_path.stat().st_size,
"sha256": sha256.hexdigest(),
},
timeout=60,
)
response.raise_for_status()
application = response.json()
upload = application["upload"]
if upload is not None:
with file_path.open("rb") as audio:
response = requests.put(
upload["url"],
headers=upload["headers"],
data=audio,
timeout=600,
allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"Upload failed: HTTP {response.status_code}")
response = requests.post(
f"{base_url}/transcriptions",
headers=api_headers,
json={"uploadId": application["uploadId"], "speakerLabels": False},
timeout=60,
)
response.raise_for_status()
print(response.json())
创建 POST 只发送一次,示例不会自动重试。使用返回的任务 id,按转录文档查询结果。
浏览器上传时,须能按全部返回请求头向签名上传地址发出 PUT。MCP 提供 request_file_upload 工具,由客户端执行 PUT 后调用 transcribe。
上传错误
| Code | 含义 |
|---|---|
insufficient_credits | API 积分余额不大于 0(HTTP 402) |
upload_not_found | 上传 ID 不存在或不属于当前账号(HTTP 404) |
upload_unavailable | 当前无法确认上传;作为请求错误时返回 HTTP 503 |
invalid_file | 文件无效或不是音频 |
file_too_large | 文件超过 1 GiB |
hash_mismatch | 上传的原始字节与声明的 SHA-256 不一致 |
文件校验可能在转录任务受理后才完成。任务失败时,轮询读取任务的 error.code 和 error.message;处理中的任务和已完成任务的 error 为 null。准备失败也可能返回 upload_unavailable 或 hash_mismatch,不扣转录积分。摘要不匹配时,先用未修改的原文件重新计算摘要,再申请上传。已经返回任务 ID 时,先查询原任务,再考虑重新创建。详见错误码。