Logo

文件管理

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

上传文件

基本信息

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

请求头

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

表单参数

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

ℹ️ 说明：当前后端限制单文件最大 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 状态码说明解决方案
6001400不支持的文件类型上传受支持的扩展名
6002413文件超过 20 GB压缩文件后重试
6011400空文件检查文件是否实际包含内容
6502401鉴权失败检查 Authorization 是否直接传入 API Key

获取文件详情

基本信息

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

路径参数

参数名类型必填说明
file_idstring是上传接口返回的文件 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

下一步