外观
请求预签名直传：服务端鉴权 + 配额预检 + 签 PUT URL（V1 两段式第一段）
POST
/v1/versions/presign-upload
V1 两段式直传的第一段。客户端声明目标（docId 已有文档 / containerId+title 新建文档，二选一）+ 文件元信息；服务端完成鉴权与配额预检后决定对象存储位置，不接受客户端在请求体或 URL 上指定存储位置。返回 mode=presigned 时携带 presignedUrl / expiresAt / httpMethod=PUT / signedHeaders（仅 Content-Type），该 URL 限时、仅可对单个对象执行一次 PUT；当前后端不支持预签名直传时返回 mode=fallback，客户端改调 /v1/versions/upload 走 multipart 上传。客户端 PUT 完成后必须回调 /v1/versions/finalize-upload 触发 Version 建立——finalize 之前对象不构成正式 Version，不可见。content_hash 客户端可选声明、服务端不重算不校验，且不参与内容去重；直传内容与 /upload 上传内容的去重相互独立，同一内容用两种方式上传会产生独立的存储记录。
授权
apiKey
类型
API Key (header: Authorization)
参数
请求头参数
X-Atk-User-Token
强通道：系统自签的不透明用户会话 token，用于 Client 代表用户调用。 与 X-Atk-Act-As-Source / X-Atk-Act-As-Source-Id 互斥，同时携带服务端返回 400 INVALID_DELEGATION_HEADERS。
类型
string
X-Atk-Act-As-Source
弱通道：身份 source 主张（要求 Client 已开启 actAsAllowed）。 必须与 X-Atk-Act-As-Source-Id 成对携带，缺一服务端返回 400 INCOMPLETE_ACT_AS_HEADERS；与 X-Atk-User-Token 互斥，同时携带服务端返回 400 INVALID_DELEGATION_HEADERS。
类型
string
X-Atk-Act-As-Source-Id
弱通道：身份 sourceId 主张（要求 Client 已开启 actAsAllowed）。 必须与 X-Atk-Act-As-Source 成对携带，缺一服务端返回 400 INCOMPLETE_ACT_AS_HEADERS；与 X-Atk-User-Token 互斥，同时携带服务端返回 400 INVALID_DELEGATION_HEADERS。
类型
string
请求体
application/json
JSON "docId": "string", "containerId": "string", "title": "string", "documentTypeId": "string", "sizeBytes": 0, "mimeType": "string", "originalFilename": "string", "idempotencyKey": "string", "expectedContentHash": "string", "metadata": "string", "comment": "string", "label": "string"
{
}
响应
OK
*/*
JSON "code": 0, "data": { "mode": "string", "uploadId": "string", "presignedUrl": "string", "expiresAt": "string", "httpMethod": "string", "signedHeaders": [ "string" ], "fallbackEndpoint": "string" }, "ts": 0, "rid": "string", "msg": "string", "success": true
{
}