文件与媒体

适用场景

发图、文件、视频等媒体：平台要求先完成上传登记拿到 file_id，再调用对应 send*。小流量也可用部分「URL 入站」接口（见 API），但直传更稳。

步骤

1. POST /api/v1/bots/files/upload-credentials 申请直传凭证（必填 fileName、fileSize、checksum）。
2. 若响应 uploadRequired: true（或缺省），按返回的 uploadUrl / headers PUT 直传对象存储。
3. POST /api/v1/bots/files/complete 登记（同样必填 checksum），响应里的 file_id 留给发送接口。
4. 调用 sendPhoto / sendDocument / sendVideo / sendAudio 等；可用 caption、reply_to_message_id。

内容去重（秒传）

凭证请求必填完整文件 checksum，并建议附带稳定的 reuseRequestId（同一次上传与重试保持相同，不同上传使用新值）。若响应返回 uploadRequired: false 和可用的 file / file_id，请跳过 PUT 与 complete。reuseExisting 为可选字段，可省略。

• 使用当前上传请求返回的 file_id，不要跨消息缓存旧值。
• 低层 HTTP 只要带齐 checksum + reuseRequestId 即可参与秒传；官方 Node sendPhotoFromFile 等 helper 会自动计算 checksum 并带幂等键。
• 若响应含 possessionRequired / possessionChallenge，需先完成持有证明再继续。

示例

curl -X POST "$API/bots/files/upload-credentials" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "photo.jpg",
  "fileSize": 12345,
  "fileType": "image/jpeg",
  "checksum": "<64-char-sha256-hex>",
  "reuseRequestId": "upload-<stable-uuid>"
}'
# 命中秒传：{ "uploadRequired": false, "file": { "file_id": "…" }, … }
# 未命中：{ "uploadRequired": true, "uploadUrl": "…", "key": "…", "headers": {…} }

curl -X POST "$API/bots/files/complete" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "<object-key>",
  "fileName": "photo.jpg",
  "fileSize": 12345,
  "fileType": "image/jpeg",
  "checksum": "<64-char-sha256-hex>",
  "reuseRequestId": "upload-<stable-uuid>"
}'

curl -X POST "$API/bots/sendPhoto" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "<chat_id>",
  "file_id": "<file_id>",
  "caption": "说明文字"
}'

约束与错误

• upload-credentials 与 files/complete 均必填 checksum（64 位 SHA-256 十六进制）；另需 key（complete）、fileName、fileSize。
• sendPhoto 等必填 chat_id + file_id（来自 complete 或秒传响应，不是随意字符串）。
• 查元数据 / 临时下载链：GET /api/v1/bots/getFile?file_id=…。

下一步

文件 API · 消息发送 API · Node SDK。