Logo

API 参考

同合云公开接口采用统一的 HTTP + JSON 设计，覆盖用户信息、文件管理、任务管理，以及图片 / 音频 / 视频处理能力。本文汇总通用约定，便于你快速理解所有接口的共性。

基础信息

项目值
Base URLhttps://api.ai-mcn.tv:10000
协议HTTPS
数据格式JSON，文件上传接口使用 multipart/form-data
鉴权方式Authorization 请求头直接传 API Key

鉴权约定

所有业务接口都要求在请求头中携带 API Key：

Authorization: YOUR_API_KEY

⚠️ 注意：系统不会解析 Bearer 前缀。若写成 Authorization: Bearer YOUR_API_KEY，会直接鉴权失败。

详细说明请参见 鉴权方式。

请求规范

  • 文件上传接口：POST /base/file/upload，使用 multipart/form-data
  • 其余大多数接口：使用 application/json
  • 所有处理类接口都基于异步任务模型，先创建任务，再查询任务结果
  • 时间字段统一为 ISO 8601 风格字符串

统一响应格式

所有接口都会返回以下结构：

{
  "code": 200,
  "msg": "success",
  "data": {}
}
字段类型说明
codenumber业务状态码。成功时通常为 200
msgstring状态说明或错误信息
dataobject / string / null响应数据。部分接口成功时也可能返回空字符串

任务状态

状态值说明
created任务已创建，尚未进入队列
queued任务已入队，等待处理
processing任务处理中
completed任务处理完成
failed任务处理失败
cancelled任务已取消

文件生命周期

  • 上传文件默认保留 60 天
  • 同内容文件重复上传时，系统会根据指纹复用已有文件记录
  • 文件过期后可被续期或重新上传

媒体文件限制

音频和视频类任务创建时会先检查输入文件。不满足以下要求时直接返回对应错误码，不创建任务、不扣费：

项目要求不满足时的错误码
文件完整性文件能被正常解析和解码6017 / 6021
时长大于 0，且不超过 2 小时6019
视频分辨率宽和高都不超过 4000 像素。常见的 3840×2160 可以处理，4096×2160 会超限6022
视频帧率不超过 120 fps6023

部分接口还有更严格的限制，例如视频超分仅支持 1 分钟以内的视频，去水印的 raft 算法仅支持 20 分钟以内的视频，以各接口文档为准。

通用错误码

错误码HTTP 状态码说明解决方案
400400请求参数或请求体格式错误检查 JSON 格式和参数类型
401401未认证检查请求头 Authorization
413413请求体过大压缩文件或缩小请求内容
415415Content-Type 不受支持使用 application/json 或 multipart/form-data
6001400不支持的文件类型使用受支持的媒体格式
6002413文件大小超过限制上传 20 GB 以内文件
6004404文件不存在检查 file_id 是否正确
6006404任务不存在检查 task_id 是否正确
6007400当前任务状态不允许取消仅 created / queued 状态支持取消
6013400必填参数缺失补充缺失字段
6014400文件类型与任务类型不匹配确认上传文件与接口能力一致
6015400语言代码不受支持使用系统支持的语言代码
6016400任务参数类型或取值非法检查字段类型与枚举值
6017400媒体文件无法解析：文件损坏、格式异常，或元信息互相矛盾用剪辑或转码工具重新导出后上传
6019400媒体时长为 0 或超过 2 小时截短媒体后重试
6021400媒体完整性校验失败：部分位置无法解码，或文件末尾不完整更换源文件，或重新导出完整文件后上传
6022400视频分辨率超出限制：宽或高超过 4000 像素（视频超分按放大后的分辨率计算）将视频缩放到宽和高都不超过 4000 像素，或降低输出倍率
6023400视频帧率超过 120 fps将视频转为 120 fps 以内（如 60 fps）后重新上传
6201402配额不足购买配额包或充值
6202402余额不足前往仪表盘充值
6502401鉴权失败使用真实 API Key 填充 Authorization 请求头
500500服务器内部错误稍后重试，必要时联系支持

接口分类