分片上传

分片上传适用于大文件场景，通过将文件切分为多个分片逐个上传，最后合并为完整文件。相比普通上传，分片上传支持断点续传、避免单次请求超时，适合超过 5MB 的文件。

INFO

每个分片建议不超过 5MB，total_chunks 根据文件大小合理划分。小文件（≤5MB）直接使用普通上传即可。

上传流程

完整的分片上传流程如下：

初始化 — 调用初始化分片上传获取 upload_id
上传分片 — 循环调用上传分片，将文件按序切分逐个上传，保存每次返回的 etag 和 size
完成上传 — 所有分片上传完毕后，调用完成分片上传合并分片
查询状态（可选） — 可随时调用查询上传状态确认已上传的分片进度，支持断点续传
取消上传（可选） — 如需中止，调用取消分片上传，已上传的分片数据将被清除

完整示例（curl）：

以下示例将一个 15MB 文件切分为 3 个分片上传：

bash

# 步骤1：初始化分片上传
curl -X POST "https://runtime-api.invalid/v1/openapi/app/files/upload/multipart/init" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user123","path":"/data/large-file.csv","total_chunks":3}'

# 返回: {"data":{"upload_id":"01965de1-1920-7fe4-aa38-2e6836c46f22","path":"/data/large-file.csv"}}

# 步骤2：逐个上传分片
curl -X POST "https://runtime-api.invalid/v1/openapi/app/files/upload/multipart/part" \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@chunk_1.bin" \
  -F "user_id=user123" \
  -F "path=/data/large-file.csv" \
  -F "upload_id=01965de1-1920-7fe4-aa38-2e6836c46f22" \
  -F "part_number=1"

# 返回: {"data":{"part_number":1,"etag":"a1b2c3d4e5f6","size":5242880}}

curl -X POST "https://runtime-api.invalid/v1/openapi/app/files/upload/multipart/part" \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@chunk_2.bin" \
  -F "user_id=user123" \
  -F "path=/data/large-file.csv" \
  -F "upload_id=01965de1-1920-7fe4-aa38-2e6836c46f22" \
  -F "part_number=2"

# 返回: {"data":{"part_number":2,"etag":"b2c3d4e5f6g7","size":5242880}}

curl -X POST "https://runtime-api.invalid/v1/openapi/app/files/upload/multipart/part" \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@chunk_3.bin" \
  -F "user_id=user123" \
  -F "path=/data/large-file.csv" \
  -F "upload_id=01965de1-1920-7fe4-aa38-2e6836c46f22" \
  -F "part_number=3"

# 返回: {"data":{"part_number":3,"etag":"c3d4e5f6g7h8","size":3145728}}

# 步骤3：完成分片上传（合并所有分片）
curl -X POST "https://runtime-api.invalid/v1/openapi/app/files/upload/multipart/complete" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id":"user123",
    "path":"/data/large-file.csv",
    "upload_id":"01965de1-1920-7fe4-aa38-2e6836c46f22",
    "parts":[
      {"part_number":1,"etag":"a1b2c3d4e5f6","size":5242880},
      {"part_number":2,"etag":"b2c3d4e5f6g7","size":5242880},
      {"part_number":3,"etag":"c3d4e5f6g7h8","size":3145728}
    ]
  }'

# 返回: {"data":{"name":"large-file.csv","path":"/data/large-file.csv","size":13631488,...}}

初始化分片上传（init）

为大文件上传初始化分片上传任务，返回 upload_id 供后续分片上传使用。

接口路径：POST /v1/openapi/app/files/upload/multipart/init

请求头

参数名	必填	说明
Content-Type	是	`application/json`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

json

{
  "user_id": "user123",
  "path": "/data/large-file.csv",
  "total_chunks": 10
}

参数名	类型	必填	说明
user_id	string	是	业务方用户 ID，用于确定所属工作空间
path	string	是	目标文件路径
total_chunks	int	是	总分片数量，最小为 `1`

响应示例

json

{
  "code": 200,
  "data": {
    "upload_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
    "path": "/data/large-file.csv"
  },
  "message": "",
  "trace_id": "abc123"
}

字段	类型	说明
upload_id	string	分片上传任务 ID，后续上传分片、完成上传、查询状态均需此 ID
path	string	目标文件路径

上传分片（part）

在分片上传任务中上传单个文件分片，使用 multipart/form-data 格式提交。

接口路径：POST /v1/openapi/app/files/upload/multipart/part

请求头

参数名	必填	说明
Content-Type	是	`multipart/form-data`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

参数名	类型	必填	说明
file	file	是	当前分片的文件数据
user_id	string	是	业务方用户 ID
path	string	是	目标文件路径
upload_id	string	是	分片上传任务 ID，由初始化返回
part_number	int	是	分片编号，从 `1` 开始递增

请求示例（curl）：

bash

curl -X POST "https://runtime-api.invalid/v1/openapi/app/files/upload/multipart/part" \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@chunk_1.bin" \
  -F "user_id=user123" \
  -F "path=/data/large-file.csv" \
  -F "upload_id=01965de1-1920-7fe4-aa38-2e6836c46f22" \
  -F "part_number=1"

响应示例

json

{
  "code": 200,
  "data": {
    "part_number": 1,
    "etag": "a1b2c3d4e5f6",
    "size": 5242880
  },
  "message": "",
  "trace_id": "abc123"
}

字段	类型	说明
part_number	number	分片编号
etag	string	分片校验标识，完成上传时需提供
size	number	分片大小（字节）

WARNING

每个分片的 part_number 必须与初始化时声明的 total_chunks 对应，且从 1 开始连续编号。请保存每次上传返回的 etag 和 size，完成上传时需要提交所有分片信息。

完成分片上传（complete）

所有分片上传完毕后，合并所有分片完成文件上传。

接口路径：POST /v1/openapi/app/files/upload/multipart/complete

请求头

参数名	必填	说明
Content-Type	是	`application/json`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

json

{
  "user_id": "user123",
  "path": "/data/large-file.csv",
  "upload_id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
  "parts": [
    {
      "part_number": 1,
      "etag": "a1b2c3d4e5f6",
      "size": 5242880
    },
    {
      "part_number": 2,
      "etag": "b2c3d4e5f6g7",
      "size": 5242880
    },
    {
      "part_number": 3,
      "etag": "c3d4e5f6g7h8",
      "size": 3145728
    }
  ]
}

参数名	类型	必填	说明
user_id	string	是	业务方用户 ID
path	string	是	目标文件路径
upload_id	string	是	分片上传任务 ID
parts	array	是	所有分片信息列表，按 `part_number` 排序

parts 字段结构：

字段	类型	必填	说明
part_number	number	是	分片编号
etag	string	是	分片校验标识，由上传分片返回
size	number	是	分片大小（字节），由上传分片返回

响应示例

json

{
  "code": 200,
  "data": {
    "name": "large-file.csv",
    "path": "/data/large-file.csv",
    "size": 13631488,
    "is_dir": false,
    "mod_time": "2026-05-10T14:00:00Z",
    "url": "https://obs.example.com/workspaces/.../data/large-file.csv"
  },
  "message": "",
  "trace_id": "abc123"
}

响应 data 字段结构见文件对象结构。

WARNING

调用此接口前，请确保所有分片已通过上传分片接口上传完毕。parts 数组中的分片信息必须与上传时返回的 etag 和 size 完全一致，否则合并可能失败。

查询上传状态（status）

查询指定分片上传任务中已成功上传的分片列表及进度信息。

接口路径：POST /v1/openapi/app/files/upload/multipart/status

请求头

参数名	必填	说明
Content-Type	是	`application/json`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

json

{
  "user_id": "user123",
  "path": "/data/large-file.csv",
  "upload_id": "01965de1-1920-7fe4-aa38-2e6836c46f22"
}

参数名	类型	必填	说明
user_id	string	是	业务方用户 ID
path	string	是	目标文件路径
upload_id	string	是	分片上传任务 ID

响应示例

json

{
  "code": 200,
  "data": {
    "path": "/data/large-file.csv",
    "parts": [
      {
        "part_number": 1,
        "etag": "a1b2c3d4e5f6",
        "size": 5242880
      },
      {
        "part_number": 2,
        "etag": "b2c3d4e5f6g7",
        "size": 5242880
      }
    ],
    "total_chunks": 10,
    "received_chunks": 2
  },
  "message": "",
  "trace_id": "abc123"
}

字段	类型	说明
path	string	目标文件路径
parts	array	已上传成功的分片列表
total_chunks	number	总分片数量
received_chunks	number	已成功上传的分片数量

parts 字段结构：

字段	类型	说明
part_number	number	分片编号
etag	string	分片校验标识
size	number	分片大小（字节）

TIP

此接口可用于断点续传场景：上传中断后，先查询已完成的分片，仅上传缺失的分片，避免重复上传。

取消分片上传（abort）

取消指定分片上传任务，清除已上传的分片数据。

接口路径：POST /v1/openapi/app/files/upload/multipart/abort

请求头

参数名	必填	说明
Content-Type	是	`application/json`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

json

{
  "user_id": "user123",
  "path": "/data/large-file.csv",
  "upload_id": "01965de1-1920-7fe4-aa38-2e6836c46f22"
}

参数名	类型	必填	说明
user_id	string	是	业务方用户 ID
path	string	是	目标文件路径
upload_id	string	是	分片上传任务 ID

响应示例

json

{
  "code": 200,
  "data": true,
  "message": "",
  "trace_id": "abc123"
}

WARNING

取消操作不可恢复，所有已上传的分片数据将被清除。如需重新上传，需重新调用初始化分片上传获取新的 upload_id。

分片上传 ​

上传流程 ​

初始化分片上传（init） ​

请求头 ​

请求参数 ​

响应示例 ​

上传分片（part） ​

请求头 ​

请求参数 ​

响应示例 ​

完成分片上传（complete） ​

请求头 ​

请求参数 ​

响应示例 ​

查询上传状态（status） ​

请求头 ​

请求参数 ​

响应示例 ​

取消分片上传（abort） ​

请求头 ​

请求参数 ​

响应示例 ​

分片上传

上传流程

初始化分片上传（init）

请求头

请求参数

响应示例

上传分片（part）

请求头

请求参数

响应示例

完成分片上传（complete）

请求头

请求参数

响应示例

查询上传状态（status）

请求头

请求参数

响应示例

取消分片上传（abort）

请求头

请求参数

响应示例