文件上传

本地音频先申请上传,需要时按返回的地址与请求头上传文件,再用 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_creditsAPI 积分余额不大于 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 时,先查询原任务,再考虑重新创建。详见错误码。