智能拼图 / 封面图

根据多张图片和标题文字，AI 智能计算最佳布局，生成优质的图文拼图或封面图，适用于社交媒体内容制作。

不想写代码？在同合智创工具箱里直接上传文件处理，登录即用，结果与本接口一致。打开「智能拼图/封面图」→

示例效果

创建任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/image_classic_template`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_ids`	`array`	是	—	图片文件 ID 数组，支持多张图片
`main_title`	`string`	`full` / `text` 时必填	—	主标题文本，可用文字见下文「标题可用文字」；`mode` 为 `image` 时可不传
`sub_title`	`string`	否	`""`	副标题文本，可用文字同 `main_title`
`mode`	`string`	否	`"full"`	生成模式：`full`（封面＝拼图 + 标题）/ `image`（只要拼图）/ `text`（只要标题层）
`aspect`	`string`	否	`"3:4"`	画幅比例：`"1:1"` / `"3:4"` / `"4:3"` / `"9:16"` / `"16:9"`
`quality`	`string`	否	`"1080p"`	输出质量：`"360p"` / `"720p"` / `"1080p"` / `"2k"` / `"4k"`
`output_pic_count`	`number`	否	`0`	候选组数，最多 20；`0` 按图片张数自动（1 张出 1 组、2 张出 5 组、6 张及以上出 10 组）
`output_text_count`	`number`	否	`1`	图文版本数量（最多 20）

任一张图片读不出时整单失败，不会跳过这一张、用其余图片出图：认不出是图片的文件在建单时直接返回 6017，不创建任务、不扣费；数据不完整的图片（如下载中断造成的截断）要到任务执行时才发现，此时任务以 6021 失败、积分自动退回，error 会指名是第几张（按 file_ids 顺序从 1 数起）。

标题可用文字

标题（main_title、sub_title）可以写：中文（简体、繁体）、日文、韩文、泰文、拉丁字母（含越南文、法文、德文等带附加符号的字母）、西里尔字母（俄文、乌克兰文、白俄罗斯文、保加利亚文、塞尔维亚文等）、数字与常用标点。标题较长时会自动缩小字号放进画面。

emoji、阿拉伯文、哈萨克文等扩展西里尔字母这类封面字体画不出的字符会在建单时返回 6046，不创建任务、不扣费；mode 为 image 时不检查标题。

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/image_classic_template \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_ids": ["537489015178246", "537489015178247"],
    "main_title": "精彩瞬间",
    "sub_title": "2026 年度回顾",
    "mode": "full",
    "aspect": "3:4",
    "output_text_count": 3
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178248",
    "task_type": "image_classic_template",
    "status": "queued"
  }
}

查询任务结果

基本信息

项目	值
请求方法	`GET`
请求路径	`/task/image_classic_template/{task_id}`
鉴权方式	`Authorization` 请求头（直接传 API Key）

响应参数（output_result）

参数名	类型	说明
`render_file_download_url_list`	`array`	封面（拼图 + 标题）下载链接，JPG；`mode` 为 `image` 时为空
`render_file_id_list`	`array`	封面文件 ID，与上一项一一对应
`pic_file_download_url_list`	`array`	纯拼图下载链接，JPG
`pic_file_id_list`	`array`	纯拼图文件 ID
`text_file_download_url_list`	`array`	透明底标题层下载链接，PNG，可叠在拼图上自己排版；`mode` 为 `image` 时为空
`text_file_id_list`	`array`	标题层文件 ID

同一下标的封面、拼图、标题层属于同一组候选。

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178248",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "render_file_download_url_list": ["https://api.ai-mcn.tv:9000/cloud/file/1e/537489015178249.jpg"],
      "render_file_id_list": ["537489015178249"],
      "pic_file_download_url_list": ["https://api.ai-mcn.tv:9000/cloud/file/7a/537489015178250.jpg"],
      "pic_file_id_list": ["537489015178250"],
      "text_file_download_url_list": ["https://api.ai-mcn.tv:9000/cloud/file/7b/537489015178251.png"],
      "text_file_id_list": ["537489015178251"]
    },
    "create_time": "2026-04-05T08:00:00Z",
    "update_time": "2026-04-05T08:00:15Z"
  }
}

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	`file_ids` 缺失，或 `mode` 为 `full` / `text` 时缺 `main_title`	补充必填参数
`6046`	400	标题里有封面字体画不出的字符（如 emoji）	删掉这些字符后重试；不扣费
`6004`	404	文件不存在	检查 `file_ids` 中的 ID 是否正确
`6017`	400	`file_ids` 中有文件不是可识别的图片（如伪装成 `.jpg` 的网页、文件头残缺），整个请求被拒绝，不创建任务、不扣费	逐张检查，把有问题的图片重新导出为 JPEG / PNG 后上传
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6202`	402	余额不足	前往仪表盘充值
`6021`	—	其中一张图片数据不完整或已损坏（常见于下载或上传中断造成的截断），整单失败，`error` 会指名第几张（任务执行阶段：任务失败、积分退回，错误码见任务结果的 `error_code`）	重新导出这张图或换用原图后重新提交