API 参考
同合云公开接口采用统一的 HTTP + JSON 设计，覆盖用户信息、文件管理、任务管理，以及图片 / 音频 / 视频处理能力。本文汇总通用约定，便于你快速理解所有接口的共性。
基础信息
| 项目 | 值 |
|---|---|
| Base URL | https://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": {}
}
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 业务状态码。成功时通常为 200 |
msg | string | 状态说明或错误信息 |
data | object / string / null | 响应数据。部分接口成功时也可能返回空字符串 |
任务状态
| 状态值 | 说明 |
|---|---|
created | 任务已创建，尚未进入队列 |
queued | 任务已入队，等待处理 |
processing | 任务处理中 |
completed | 任务处理完成 |
failed | 任务处理失败 |
cancelled | 任务已取消 |
文件生命周期
- 上传文件默认保留 60 天
- 同内容文件重复上传时，系统会根据指纹复用已有文件记录
- 文件过期后可被续期或重新上传
通用错误码
| 错误码 | HTTP 状态码 | 说明 | 解决方案 |
|---|---|---|---|
400 | 400 | 请求参数或请求体格式错误 | 检查 JSON 格式和参数类型 |
401 | 401 | 未认证 | 检查请求头 Authorization |
413 | 413 | 请求体过大 | 压缩文件或缩小请求内容 |
415 | 415 | Content-Type 不受支持 | 使用 application/json 或 multipart/form-data |
6001 | 400 | 不支持的文件类型 | 使用受支持的媒体格式 |
6002 | 413 | 文件大小超过限制 | 上传 20 GB 以内文件 |
6004 | 404 | 文件不存在 | 检查 file_id 是否正确 |
6006 | 404 | 任务不存在 | 检查 task_id 是否正确 |
6007 | 400 | 当前任务状态不允许取消 | 仅 created / queued 状态支持取消 |
6013 | 400 | 必填参数缺失 | 补充缺失字段 |
6014 | 400 | 文件类型与任务类型不匹配 | 确认上传文件与接口能力一致 |
6015 | 400 | 语言代码不受支持 | 使用系统支持的语言代码 |
6016 | 400 | 任务参数类型或取值非法 | 检查字段类型与枚举值 |
6019 | 400 | 媒体时长不合法或超限 | 截短媒体后重试 |
6022 | 400 | 视频分辨率超出限制 | 降低输入分辨率或输出倍率 |
6201 | 402 | 配额不足 | 购买配额包或充值 |
6202 | 402 | 余额不足 | 前往仪表盘充值 |
6502 | 401 | 鉴权失败 | 使用真实 API Key 填充 Authorization 请求头 |
500 | 500 | 服务器内部错误 | 稍后重试，必要时联系支持 |