文生图

用文字描述生成图片。一次可出 1–4 张，可选画幅比例、引擎，还可以带 0–4 张参考图来锁定人物、画风或构图。

三个引擎画风各有不同，单价也不同：

引擎	`engine` 取值	说明
Seedream	`seedream`（默认）	提示词与参考图由境内模型服务处理；主渠道暂时不可用时，会改由境外渠道处理同一模型
Gemini	`gemini`	提示词与参考图会发送给中国大陆以外的第三方模型服务处理
GPT	`gpt`	提示词与参考图会发送给中国大陆以外的第三方模型服务处理

创建任务

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
`prompt`	`string`	是	—	画面描述，去掉首尾空白后 1–2000 个字符。不想出现的东西也写在这里，例如 "no text"
`aspect_ratio`	`string`	否	`1:1`	画幅比例：`1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`。具体尺寸由服务端按引擎换算，见输出尺寸
`n`	`integer`	否	`1`	出几张，1–4
`engine`	`string`	否	`seedream`	引擎：`seedream` / `gemini` / `gpt`，决定画风与单价
`reference_file_ids`	`string[]`	否	`[]`	参考图：0–4 个已上传图片的文件 ID（png / jpg / jpeg / webp），用来锁定人物、画风或构图

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/image_generate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A quiet lake at dawn, soft mist, no text", "aspect_ratio": "16:9", "n": 2}'

带参考图、用 Gemini 引擎：

curl -X POST https://api.ai-mcn.tv:10000/task/image_generate \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Same character as the reference, full body, standing in a bamboo forest, no text", "aspect_ratio": "3:4", "engine": "gemini", "reference_file_ids": ["537489015178246"]}'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "task_type": "image_generate",
    "status": "queued"
  }
}

task_type 随引擎不同：seedream 为 image_generate，gemini 为 image_generate_gemini，gpt 为 image_generate_gpt。

查询任务结果

基本信息

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

三个引擎的任务都用这一个查询接口。

响应参数（output_result）

三个列表按出图顺序一一对应，长度为实际出图张数。

参数名	类型	说明
`pic_file_id_list`	`string[]`	图片文件 ID
`pic_file_download_url_list`	`string[]`	图片下载路径
`pic_size_list`	`object[]`	每张图的实际宽高 `{"width", "height"}`
`engine`	`string`	本单的引擎
`aspect_ratio`	`string`	本单的画幅比例

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "pic_file_id_list": ["537489015178248", "537489015178249"],
      "pic_file_download_url_list": ["/download/a1/1.jpg", "/download/a1/2.jpg"],
      "pic_size_list": [{"width": 2048, "height": 1152}, {"width": 2048, "height": 1152}],
      "engine": "seedream",
      "aspect_ratio": "16:9"
    },
    "create_time": "2026-11-11T08:00:00Z",
    "update_time": "2026-11-11T08:01:20Z"
  }
}

输出尺寸

比例	`seedream`	`gemini`	`gpt`
1:1	1536 × 1536	1024 × 1024	1280 × 1280
16:9	2048 × 1152	1376 × 768	1536 × 864
9:16	1152 × 2048	768 × 1376	864 × 1536
4:3	1728 × 1296	1200 × 896	1536 × 1152
3:4	1296 × 1728	896 × 1200	1152 × 1536
3:2	1872 × 1248	1264 × 848	1536 × 1024
2:3	1248 × 1872	848 × 1264	1024 × 1536

格式：PNG 或 JPEG，保留模型返回的格式，不重新编码。
实际宽高以 pic_size_list 为准；个别情况下与上表相差几个像素。

参考图

每张图都会带上全部参考图。参考图先按拍摄方向摆正，透明背景按白底处理，长边缩到 2048 以内再发送，你上传的原图不会被改动。
参考图越贴近你想要的人物或画风，效果越稳定；同一个人物的几个角度，比几张不同人物的图更容易保持一致。
gemini、gpt 引擎会把参考图发送给中国大陆以外的第三方模型服务处理。

计费

按张计费，三个引擎各有单价，见价格说明。
提交时按张数预扣；实际出图少于请求张数时，按实际张数结算，差额退回。
一张都没出（包括提示词或参考图没通过模型服务的内容审核）时，任务失败，预扣的积分全额退回。

处理时长

seedream 单张约 1 分钟，gemini 约 10–20 秒，gpt 约 20–30 秒（不含排队）。一单多张时，seedream、gpt 并发出图，gemini 逐张出图。任务为异步执行，提交后请通过查询接口轮询 status。

AI 生成内容标识

结果图片带 AI 生成内容隐式标识（只写入文件元数据，不改变画面），见 AI 生成内容标识说明。公开发布时，请按平台要求另行标注「AI 生成」。

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	`prompt` 缺失	传入 `prompt`
`6016`	400	参数取值不合法：`prompt` 为空或超过 2000 个字符；`aspect_ratio`、`n`、`engine` 不在可选范围；`reference_file_ids` 不是数组或超过 4 个。不创建任务、不扣费	按请求参数修改
`6004`	404	参考图文件不存在	检查 `reference_file_ids` 里的文件 ID
`6014`	400	参考图不是 png / jpg / jpeg / webp	换成支持的图片格式
`6064`	—	提示词或参考图没通过模型服务的内容审核（任务执行阶段：任务失败、积分全额退回，错误码见任务结果的 `error_code`）	修改提示词或换参考图后重新提交
`6017` / `6021`	—	参考图无法识别或数据不完整（任务执行阶段：任务失败、积分退回）	重新导出参考图后重新提交
`6502`	401	鉴权失败	检查 `Authorization` 请求头
`6202`	402	余额不足	前往仪表盘充值