文件管理

文件管理接口负责接收原始媒体文件，并返回后续所有处理接口都会用到的 file_id。如果你要调用图片、音频或视频处理能力，通常都要先经过这一步。

上传文件

基本信息

项目	值
请求方法	`POST`
请求路径	`/base/file/upload`
Content-Type	`multipart/form-data`
鉴权方式	`Authorization` 请求头直接传 API Key

请求头

参数名	类型	必填	说明
`Authorization`	`string`	是	直接传 API Key，例如 `YOUR_API_KEY`

表单参数

参数名	类型	必填	说明
`file`	`file`	是	待上传的音频、图片、视频或文本文件

ℹ️ 说明：当前后端限制单文件最大 20 GB，并会校验文件扩展名与文件大小。

支持上传的文件类型（后缀）

当前公开文档里，上传接口已明确覆盖以下媒体后缀；如果后缀不在后端校验范围内，接口可能直接返回 6001。

文件类型	支持的后缀	说明
图片	`.jpg`、`.jpeg`、`.png`、`.webp`、`.bmp`	用于图片处理相关接口
音频	`.mp3`、`.wav`、`.m4a`、`.aac`、`.flac`、`.ogg`	用于音频处理相关接口
视频	`.mp4`、`.mov`、`.avi`、`.mkv`、`.flv`、`.webm`	用于视频处理相关接口
其它文本类素材	当前公开文档未单独列出精确后缀	建议在正式接入前先按具体任务接口要求验证

💡 提示：文件上传成功并不代表所有下游任务都能直接使用；具体处理接口仍会继续校验文件类型兼容性，不匹配时可能返回 6014。

请求示例

curl -X POST https://api.ai-mcn.tv:10000/base/file/upload \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/video.mp4"

成功响应示例

{
  "code": 200,
  "msg": "文件上传成功~",
  "data": {
    "file_id": "537489015178246",
    "original_name": "video.mp4",
    "size": 10485760,
    "blake3_id": "a1b2c3d4...",
    "base_ext": ".mp4",
    "download_url": "/download/a1/537489015178246.mp4",
    "created_at": "2026-04-05T08:00:00Z",
    "expire_at": "2026-06-04T00:00:00Z",
    "is_expired": false
  }
}

结果说明

file_id：创建任务时的唯一输入
download_url：原文件下载地址
expire_at：文件过期时间
blake3_id：文件内容指纹

💡 提示：如果上传了完全相同的文件，系统会命中去重逻辑，并直接返回已有文件记录或已续期的文件记录，不会重复存储。

错误码

错误码	HTTP 状态码	说明	解决方案
`6001`	400	不支持的文件类型	上传受支持的扩展名
`6002`	413	文件超过 20 GB	压缩文件后重试
`6011`	400	空文件	检查文件是否实际包含内容
`6502`	401	鉴权失败	检查 `Authorization` 是否直接传入 API Key

💡 提示：单发上传适合小文件。数 GB 级大文件建议使用下方的分片上传（断点续传），网络中断后只需补传缺失分片，无需整体重传。

分片上传（断点续传）

分片上传把大文件切成固定大小的分片逐个上传，任何一片失败只需重传该片；中断后可查询缺失分片列表继续上传。适合数 GB 级大文件；小文件请继续使用单发的 POST /base/file/upload。

完成后返回的文件信息与单发上传完全同构——去重、续期、保存 60 天等语义一致，下游处理接口无需区分文件来自哪条上传路径。

接口一览

接口	请求方法	请求路径	说明
创建会话	`POST`	`/base/file/upload/chunk/init`	声明文件名与总大小，返回会话与分片约定；可秒传
上传分片	`PUT`	`/base/file/upload/chunk/{upload_id}/{index}`	上传第 `index` 片原始字节，幂等可重传
查询状态	`GET`	`/base/file/upload/chunk/{upload_id}`	返回缺失分片列表，断点续传依据
完成上传	`POST`	`/base/file/upload/chunk/{upload_id}/complete`	校验齐片后入库，返回与单发上传同构的文件信息
废弃会话	`DELETE`	`/base/file/upload/chunk/{upload_id}`	主动放弃上传，幂等

所有接口的鉴权方式与单发上传一致：Authorization 请求头直接传 API Key。

断点续传流程

调用 init 声明 filename 和 size，获得 upload_id、part_size、total_parts。
按 part_size 切分文件，逐片调用上传分片接口——可乱序、可并行，同一片重传也安全。
若中途网络中断，重连后调用查询状态接口获取 missing 缺失分片列表，只补传缺失的分片。
全部分片上传完成后调用 complete，获得 file_id。

⚠️ 注意：part_size 由服务端决定（当前为 32 MiB），客户端必须以 init 响应返回的值为准切分文件，不要在代码中写死。除最后一片为余数外，每片字节数必须恰好等于 part_size。

创建会话（init）

基本信息

项目	值
请求方法	`POST`
请求路径	`/base/file/upload/chunk/init`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头直接传 API Key

请求参数（Body）

参数名	类型	必填	默认值	说明
`filename`	`string`	是	—	原始文件名（含扩展名，用于类型校验与入库记录）
`size`	`number`	是	—	文件总字节数，上限 20 GB
`blake3_id`	`string`	否	—	文件内容指纹（与单发上传去重同一口径）；提供后可能触发秒传

请求示例

curl -X POST https://api.ai-mcn.tv:10000/base/file/upload/chunk/init \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "video.mp4",
    "size": 4370031878
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "upload_id": "537489015178300",
    "part_size": 33554432,
    "total_parts": 131,
    "expires_at": "2026-07-05 12:00:00"
  }
}

upload_id：本次上传会话的唯一标识，后续四个接口都用它
part_size：每片字节数（服务端决定，客户端照此切分）
total_parts：总片数，即 ceil(size / part_size)
expires_at：会话过期时间；每次上传分片或查询状态都会顺延

ℹ️ 说明：会话默认保留 72 小时且随上传活动自动续期；超时未完成的会话会被清理，届时需重新 init 上传。

秒传

init 时携带 blake3_id，若系统中已存在未过期的相同内容文件，则直接返回该文件的完整信息（与单发上传响应同构，额外附 instant: true），零字节上传、不创建会话、不返回 upload_id：

{
  "code": 200,
  "msg": "文件已存在，已更新过期时间~",
  "data": {
    "file_id": "537489015178246",
    "original_name": "video.mp4",
    "size": 4370031878,
    "blake3_id": "a1b2c3d4...",
    "base_ext": ".mp4",
    "download_url": "/download/a1/537489015178246.mp4",
    "created_at": "2026-04-05T08:00:00Z",
    "expire_at": "2026-09-01T00:00:00Z",
    "is_expired": false,
    "instant": true
  }
}

💡 提示：客户端应先判断响应中是否有 instant: true——有则直接使用返回的 file_id，无则按分片流程继续。指纹仅命中已过期文件时不会秒传，会正常创建会话，完成上传后系统自动续期复用原记录。

上传分片（part）

基本信息

项目	值
请求方法	`PUT`
请求路径	`/base/file/upload/chunk/{upload_id}/{index}`
Content-Type	`application/octet-stream`
鉴权方式	`Authorization` 请求头直接传 API Key

路径参数

参数名	类型	必填	说明
`upload_id`	`string`	是	`init` 返回的会话 ID
`index`	`number`	是	分片序号，从 `0` 开始，小于 `total_parts`

查询参数

参数名	类型	必填	说明
`blake3`	`string`	否	该分片内容的 Blake3 校验值；提供则服务端校验，不符返回 `6026` 且该片视为未上传

请求体为该分片的原始字节（非表单）。除最后一片外，字节数必须等于 part_size；最后一片为剩余字节数。

请求示例

# 先按 init 返回的 part_size 切分文件（示例：32 MiB）
split -b 33554432 -d -a 4 video.mp4 part_

# 上传第 0 片（part_0000 对应 index=0，依此类推）
curl -X PUT "https://api.ai-mcn.tv:10000/base/file/upload/chunk/537489015178300/0" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @part_0000

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "upload_id": "537489015178300",
    "index": 0,
    "received": 1,
    "total_parts": 131
  }
}

💡 提示：分片接口是幂等的——同一片因超时重试被上传两次不会导致内容错乱；不同分片可以乱序、并行上传以提升吞吐。

查询状态（status）

基本信息

项目	值
请求方法	`GET`
请求路径	`/base/file/upload/chunk/{upload_id}`
鉴权方式	`Authorization` 请求头直接传 API Key

请求示例

curl -X GET https://api.ai-mcn.tv:10000/base/file/upload/chunk/537489015178300 \
  -H "Authorization: YOUR_API_KEY"

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "upload_id": "537489015178300",
    "size": 4370031878,
    "part_size": 33554432,
    "total_parts": 131,
    "received": 100,
    "missing": [100, 101, 102, 130],
    "expires_at": "2026-07-05 12:00:00"
  }
}

missing：缺失分片序号列表——断网重连后只需补传这些分片

完成上传（complete）

基本信息

项目	值
请求方法	`POST`
请求路径	`/base/file/upload/chunk/{upload_id}/complete`
鉴权方式	`Authorization` 请求头直接传 API Key

请求示例

curl -X POST https://api.ai-mcn.tv:10000/base/file/upload/chunk/537489015178300/complete \
  -H "Authorization: YOUR_API_KEY"

成功响应示例

响应结构与 POST /base/file/upload 完全一致：

{
  "code": 200,
  "msg": "文件上传成功~",
  "data": {
    "file_id": "537489015178246",
    "original_name": "video.mp4",
    "size": 4370031878,
    "blake3_id": "a1b2c3d4...",
    "base_ext": ".mp4",
    "download_url": "/download/a1/537489015178246.mp4",
    "created_at": "2026-07-02T08:00:00Z",
    "expire_at": "2026-08-31T00:00:00Z",
    "is_expired": false
  }
}

💡 提示：与单发上传相同，若拼装出的文件内容与系统中已有文件一致，会命中去重逻辑，返回已有记录（已续期），不会重复存储。

错误响应示例

仍有分片缺失时：

{
  "code": 6027,
  "msg": "仍有分片缺失，无法完成：缺失序号（最多列20个）[100, 101, 102]",
  "data": null
}

废弃会话（abort）

基本信息

项目	值
请求方法	`DELETE`
请求路径	`/base/file/upload/chunk/{upload_id}`
鉴权方式	`Authorization` 请求头直接传 API Key

请求示例

curl -X DELETE https://api.ai-mcn.tv:10000/base/file/upload/chunk/537489015178300 \
  -H "Authorization: YOUR_API_KEY"

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "upload_id": "537489015178300",
    "aborted": true
  }
}

ℹ️ 说明：abort 是幂等的——重复调用或对已过期的会话调用，同样返回成功。

分片上传错误码

错误码	HTTP 状态码	说明	解决方案
`6024`	404	会话不存在或已过期	重新调用 `init` 创建会话后整体重传
`6025`	400	分片不合法（序号越界 / 分片大小不符）	检查 `index` 范围与分片字节数是否符合 `init` 返回的约定
`6026`	400	分片内容校验不符	重传该分片
`6027`	400	完成时仍有分片缺失	按响应中的缺失序号补传后再次 `complete`
`6028`	400	拼装文件大小与声明不符	核对 `init` 声明的 `size` 与实际切分是否一致
`6001`	400	不支持的文件类型	上传受支持的扩展名
`6002`	413	声明大小超过 20 GB	压缩文件后重试
`6011`	400	声明大小为 0	检查文件是否实际包含内容
`6502`	401	鉴权失败	检查 `Authorization` 是否直接传入 API Key

获取文件详情

基本信息

项目	值
请求方法	`GET`
请求路径	`/base/file/{file_id}`
鉴权方式	`Authorization` 请求头直接传 API Key

路径参数

参数名	类型	必填	说明
`file_id`	`string`	是	上传接口返回的文件 ID

请求示例

curl -X GET https://api.ai-mcn.tv:10000/base/file/537489015178246 \
  -H "Authorization: YOUR_API_KEY"

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "file_id": "537489015178246",
    "original_name": "video.mp4",
    "size": 10485760,
    "blake3_id": "a1b2c3d4...",
    "base_ext": ".mp4",
    "upload_user_id": 1001,
    "download_url": "/download/a1/537489015178246.mp4",
    "created_at": "2026-04-05T08:00:00Z",
    "expire_at": "2026-06-04T00:00:00Z",
    "is_expired": false
  }
}

注意事项

文件默认保存 60 天
处理类接口创建前会校验 file_id 是否存在，且校验文件类型是否与目标接口匹配
文件过期或不存在时，会返回 6004

文件管理

上传文件

基本信息

请求头

表单参数

支持上传的文件类型（后缀）

请求示例

成功响应示例

结果说明

错误码

分片上传（断点续传）

接口一览

断点续传流程

创建会话（init）

基本信息

请求参数（Body）

请求示例

成功响应示例

秒传

上传分片（part）

基本信息

路径参数

查询参数

请求示例

成功响应示例

查询状态（status）

基本信息

请求示例

成功响应示例

完成上传（complete）

基本信息

请求示例

成功响应示例

错误响应示例

废弃会话（abort）

基本信息

请求示例

成功响应示例

分片上传错误码

获取文件详情

基本信息

路径参数

请求示例

成功响应示例

注意事项

下一步