Skip to main content
工作流可以声明 type: file 的参数。要为这类工作流提交任务, 请先上传文件,然后把返回的 file_key 作为该参数的值传入。 上传走 S3 预签名 PUT —— 不占用 API 服务器的带宽。

整体流程

按顺序三次调用:
  1. POST /api/v1/r/files/presign —— 描述文件。返回 file_keyupload_urlupload_headers
  2. PUT <upload_url> —— 把文件主体直接上传到 S3,原样发送 upload_headers 中的每一个头。
  3. POST /api/v1/r/workflows/{workflowId}/run(或 /r/workflows/slug/{workflowSlug}/run),把 file_key 作为 文件参数的值。

请求预签名 URL

响应:

上传到 S3

把文件主体作为 PUT 请求体发送,并附带 upload_headers 中的所有 请求头。签名校验这些头 —— 缺少 Content-LengthIf-None-Match 会被 S3 返回 403。如果该 key 上已经存在对象, S3 返回 412(防止覆盖)。
Content-Length 必须与第 1 步发送的 file_size 完全一致。

提交工作流

file_key 作为参数值:
任务运行时由代理从 S3 取回文件。

端到端示例

保留期和限额

  • 通过 /r/files/presign 上传的输入文件保留 1 天, 之后由 S3 生命周期策略清除。请在此窗口内提交任务。
  • 任务输出保留 7 天。之后 GET /r/tasks/{taskId}/result 返回的 download_url 不再有效。
  • 单文件默认大小上限为 500 MB。更大的上限是部署级配置。 接近或超过此上限的文件请改用分片上传端点 (/uploads/multipart/...) —— 每个分片单独预签名。

大文件分片上传

超过单次上限的文件请使用分片流程:
  1. POST /api/v1/uploads/multipart/initiate —— 开始一次上传并获取 upload ID。
  2. POST /api/v1/uploads/multipart/presign-parts —— 为每个分片请求签名 URL。
  3. 对每个签名 URL PUT 对应的分片。
  4. POST /api/v1/uploads/multipart/complete —— 完成并取回同样形态的 file_key
单次上传更简单 —— 仅在必要时使用分片。 分片端点(initiatepresign-partscomplete)只接受用户会话令牌 —— 它们会以 401 拒绝 sk- 集成凭证和 dk- 设备凭证。单次的 /r/files/presign 三者都接受。如果你用 sk-dk- 凭证调用 API, 请使用单次预签名流程。

相关