# 文件上传

> 直传音频，再用 uploadId 创建转录任务

来源: https://platform.snapany.com/zh/docs/uploads

本地音频先申请上传，需要时按返回的地址与请求头上传文件，再用 `uploadId` 创建[转录任务](https://platform.snapany.com/zh/docs/transcription)。

目前只接受**音频**，最大 **1 GiB（1,073,741,824 字节）**。本地视频请先提取音轨；已有音频或视频文件地址时，也可以直接通过 `fileUrl` 转录。

## 1. 申请上传

[`POST /uploads`](https://platform.snapany.com/zh/docs/api#POST/uploads)

申请免费，但要求 API 积分余额大于 0。鉴权沿用转录使用的 API Key。

```bash
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 时，响应为：

```json
{
  "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 提交转录

```bash
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` 的摘要、直传文件，再提交一次转录：

```python
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`，按[转录文档](https://platform.snapany.com/zh/docs/transcription)查询结果。

浏览器上传时，须能按全部返回请求头向签名上传地址发出 PUT。[MCP](https://platform.snapany.com/zh/docs/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 时，先查询原任务，再考虑重新创建。详见[错误码](https://platform.snapany.com/zh/docs/errors)。
