上传文件

上传分三步：申请上传地址、传输文件、确认文档。上传地址只能写入一次，最长有效 1 小时。

1. 申请上传地址

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json

{
  "filename": "report.docx",
  "file_size": 45678
}

字段	类型	必填	说明
filename	string	✅	文件名，服务端按扩展名确定文件类型
file_size	integer	✅	准确的字节数，必须大于 0
mime_type	string	—	可省略，服务端不使用

响应：

{
  "document_id": "4q8mx2q9z1k7p6ra",
  "upload_url": "https://upload.example/...",
  "upload_headers": {
    "Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "If-None-Match": "*"
  },
  "finalize_token": "short_lived_token",
  "expires_in": 3600
}

2. 传输文件

向 upload_url 发送 PUT，请求体为文件原始字节，并原样发送 upload_headers 中的全部请求头。

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $UPLOAD_CONTENT_TYPE" \
  -H "If-None-Match: *" \
  --upload-file "report.docx"

这一步不要携带 OmniDoc API Key。地址过期或传输失败时重新申请。

3. 确认文档

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-Type: application/json

{"finalize_token":"short_lived_token"}

成功后返回文档：

{
  "document": {
    "id": "4q8mx2q9z1k7p6ra",
    "basename": "report.docx",
    "file_size": 45678,
    "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "created_at": "2026-10-01T12:00:00Z"
  }
}

确认成功后，文档才会进入文件库，才能用于创建任务。

文件名

filename 只用于展示，不要当作路径或唯一标识。服务端会替换非法字符，并为过长的名称生成安全的下载名。

错误

状态	原因
400	文件大小无效、与实际不符，或内容与扩展名不匹配
401	凭据或 finalize_token 无效、已过期
403	finalize_token 不属于当前账号
410	未找到已上传的文件（传输未完成或地址已过期），请重新申请
413	超出单文件大小上限
415	文件格式不支持
429	上传过于频繁
503	上传服务暂时不可用，可稍后重试