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

会议录像、录屏这类可变帧率视频（标称帧率与实际平均帧率相差很大）可以正常建单：任务开始执行前会先转成固定帧率（取最接近的标准帧率，如 24、25、30 fps），会多花一些转换时间（实测 49 分钟的录像约 3–10 分钟，视服务器负载而定）；同一文件 60 天内再提交其他视频任务时直接复用转换结果。转换失败时任务以 6047 失败，积分自动退回。

图片类任务创建时只读文件头、不解码像素。认不出是图片的文件（如伪装成 .jpg 的网页、随机字节、文件头残缺）直接返回 6017，不创建任务、不扣费。文件头完好、但像素数据被截断或损坏的图片（常见于下载或上传中断）在建单时查不出，会照常建单；任务执行时以 6021 失败，积分自动退回，不重试。扩展名与实际格式不符、且该接口读不了实际格式时（如扩展名是 .jpg、内容是 AVIF），任务执行时以 6017 失败，error 会点名实际格式，积分同样退回。拼长图、智能拼图中任一张图片读不出，整单失败。

部分接口还有更严格的限制，例如视频超分仅支持 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）后重新上传
6047—可变帧率视频转固定帧率失败（任务执行阶段：任务失败、积分退回，错误码见任务结果的 error_code）导出为固定帧率的 MP4 后重新提交
6201402配额不足购买配额包或充值
6202402余额不足前往仪表盘充值
6502401鉴权失败使用真实 API Key 填充 Authorization 请求头
500500服务器内部错误稍后重试，必要时联系支持

接口分类