Ideogram V3 文生图

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口

POST /jobs/createTask

完整 URL: https://ai.modelfold.online/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

通过 ideogram/v3-text-to-image 进行生成

输出格式：WebP。

创建任务

调用该接口可创建一个新的图像生成任务。

查询任务详情 — 提交任务后，可通过统一查询接口查看任务进度并获取生成结果

TIP

生产环境建议优先使用 callBackUrl 参数接收任务完成通知，而不是持续轮询任务状态接口。

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	用于生成任务的模型名称。必填字段。 - 该端点必须使用 `ideogram/v3-text-to-image` 模型默认值：`"ideogram/v3-text-to-image"`。可选值：`ideogram/v3-text-to-image`。示例：`ideogram/v3-text-to-image`。
`callBackUrl`	`string`	否	接收任务完成通知的回调 URL。可选参数；如果提供，系统会在任务完成（成功或失败）后向该地址发送 POST 请求；如未提供，则不会发送回调通知。示例：`https://your-domain.com/api/callback`。
`input`	`object`	是	生成任务的输入参数。
`input.prompt`	`string`	是	要生成图像的描述文本（最大长度：5000 字符）。示例：`一张电影感十足的湖畔摄影作品，暮色降临，画面略带俯视角。画面中央，一簇柔和发光的芦苇与睡莲在平静水面上映出金色倒影。优雅的霓虹风白色文字“ai.modelfold.online”悬浮在水面上方，微微发光，与自然光晕和谐融合。四周垂柳与薄雾共同营造出宁静而奇幻的氛围，暖色高光与傍晚天空的冷蓝色形成鲜明对比。`。
`input.rendering_speed`	`string`	否	生成时使用的渲染速度。 - `TURBO`: 极速 - `BALANCED`: 均衡 - `QUALITY`: 高质量可选值：`TURBO` / `BALANCED` / `QUALITY`。示例：`BALANCED`。
`input.style`	`string`	否	生成时使用的风格类型。 - `AUTO`: 自动 - `GENERAL`: 通用 - `REALISTIC`: 写实 - `DESIGN`: 设计可选值：`AUTO` / `GENERAL` / `REALISTIC` / `DESIGN`。示例：`AUTO`。
`input.expand_prompt`	`boolean`	否	是否在生成请求中启用 MagicPrompt。 - 布尔值：`true` / `false` 示例：`true`。
`input.image_size`	`string`	否	生成图像的分辨率。 - `square`: 方图 - `square_hd`: 高清方图 - `portrait_4_3`: 竖图 3:4 - `portrait_16_9`: 竖图 9:16 - `landscape_4_3`: 横图 4:3 - `landscape_16_9`: 横图 16:9 可选值：`square` / `square_hd` / `portrait_4_3` / `portrait_16_9` / `landscape_4_3` / `landscape_16_9`。示例：`square_hd`。
`input.seed`	`integer`	否	随机数生成器的种子值。
`input.negative_prompt`	`string`	否	描述图像中需要排除的内容。若正向提示词与负向提示词冲突，以正向提示词为准。最大长度：5000 字符。

请求示例

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram/v3-text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "一张电影感十足的湖畔摄影作品，暮色降临，画面略带俯视角。画面中央，一簇柔和发光的芦苇与睡莲在平静水面上映出金色倒影。优雅的霓虹风白色文字“ai.modelfold.online”悬浮在水面上方，微微发光，与自然光晕和谐融合。四周垂柳与薄雾共同营造出宁静而奇幻的氛围，暖色高光与傍晚天空的冷蓝色形成鲜明对比。",
    "rendering_speed": "BALANCED",
    "style": "AUTO",
    "expand_prompt": true,
    "image_size": "square_hd",
    "seed": 123456,
    "negative_prompt": "模糊、低清晰度、畸形、额外的肢体、错位文字、水印"
  }
}'

json

{
  "model": "ideogram/v3-text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "一张电影感十足的湖畔摄影作品，暮色降临，画面略带俯视角。画面中央，一簇柔和发光的芦苇与睡莲在平静水面上映出金色倒影。优雅的霓虹风白色文字“ai.modelfold.online”悬浮在水面上方，微微发光，与自然光晕和谐融合。四周垂柳与薄雾共同营造出宁静而奇幻的氛围，暖色高光与傍晚天空的冷蓝色形成鲜明对比。",
    "rendering_speed": "BALANCED",
    "style": "AUTO",
    "expand_prompt": true,
    "image_size": "square_hd",
    "seed": 123456,
    "negative_prompt": "模糊、低清晰度、畸形、额外的肢体、错位文字、水印"
  }
}

响应

200 — 请求成功

参数	类型	必填	说明
`data`	`object`	否	—
`data.taskId`	`string`	否	任务 ID，可用于调用任务详情接口查询任务状态。示例：`task_ideogram_1765180586443`。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_ideogram_1765180586443"
  }
}

500 — 服务器错误

回调

onImageGenerated

回调地址：{$request.body#/callBackUrl}（即请求体里的 callBackUrl）。

任务成功或失败时发送回调。

回调体参数

参数	类型	必填	说明
`code`	`integer`	否	200：成功；501：失败，原因见 data.failCode 与 data.failMsg。可选值：`200` / `501`。示例：`200`。
`msg`	`string`	否	状态消息示例：`Playground task completed successfully.`。
`data`	`object`	否	—
`data.completeTime`	`integer`	否	任务完成时间，Unix 毫秒时间戳示例：`1786427040000`。
`data.costTime`	`integer`	否	处理耗时（秒），成功和失败回调都会返回。示例：`48`。
`data.createTime`	`integer`	否	任务创建时间，Unix 毫秒时间戳示例：`1786426989000`。
`data.creditsConsumed`	`number`	否	本任务消耗的积分；失败任务为 0。示例：`7`。
`data.model`	`string`	否	图片生成使用的模型示例：`ideogram/v3-text-to-image`。
`data.param`	`string`	否	创建任务时提交的参数，JSON 字符串格式示例：{"model":"ideogram/v3-text-to-image","callBackUrl":"https://your-domain.com/api/callback","input":{"prompt":"一张电影感十足的湖畔摄影作品，暮色降临，画面略带俯视角。画面中央，一簇柔和发光的芦苇与睡莲在平静水面上映出金色倒影。优雅的霓虹风白色文字“ai.modelfold.online”悬浮在水面上方，微微发光，与自然光晕和谐融合。四周垂柳与薄雾共同营造出宁静而奇幻的氛围，暖色高光与傍晚天空的冷蓝色形成鲜明对比。","rendering_speed":"BALANCED","style":"AUTO","expand_prompt":true,"image_size":"square_hd","seed":123456,"negative_prompt":"模糊、低清晰度、畸形、额外的肢体、错位文字、水印"}}。
`data.resultJson`	`string`	否	图片生成结果，JSON 字符串格式。resultUrls 为生成图片的 URL 列表。仅在 state 为 success 时出现。示例：`{"resultUrls":["https://tempfile.aiquickdraw.com/workers/images/image_90b6bf4499a80b74a2b5ee640b7aaf70.webp"]}`。
`data.state`	`string`	否	任务状态可选值：`success` / `fail`。示例：`success`。
`data.taskId`	`string`	否	任务 ID 示例：`4e029a320e97cff234e6e06827c3965e`。
`data.updateTime`	`integer`	否	完成时间请以 completeTime 为准；updateTime 可能与 createTime 相同。示例：`1786427040000`。
`data.failCode`	`string`	否	失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。示例：`500`。
`data.failMsg`	`string`	否	失败原因，仅在 state 为 fail 时出现。示例：`<error detail>`。

成功

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "4e029a320e97cff234e6e06827c3965e",
    "model": "ideogram/v3-text-to-image",
    "state": "success",
    "param": "{\"model\":\"ideogram/v3-text-to-image\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"一张电影感十足的湖畔摄影作品，暮色降临，画面略带俯视角。画面中央，一簇柔和发光的芦苇与睡莲在平静水面上映出金色倒影。优雅的霓虹风白色文字“ai.modelfold.online”悬浮在水面上方，微微发光，与自然光晕和谐融合。四周垂柳与薄雾共同营造出宁静而奇幻的氛围，暖色高光与傍晚天空的冷蓝色形成鲜明对比。\",\"rendering_speed\":\"BALANCED\",\"style\":\"AUTO\",\"expand_prompt\":true,\"image_size\":\"square_hd\",\"seed\":123456,\"negative_prompt\":\"模糊、低清晰度、畸形、额外的肢体、错位文字、水印\"}}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/workers/images/image_90b6bf4499a80b74a2b5ee640b7aaf70.webp\"]}",
    "completeTime": 1786427040000,
    "createTime": 1786426989000,
    "costTime": 48,
    "creditsConsumed": 7,
    "updateTime": 1786427040000
  }
}

失败

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "4e029a320e97cff234e6e06827c3965e",
    "model": "ideogram/v3-text-to-image",
    "state": "fail",
    "param": "{\"model\":\"ideogram/v3-text-to-image\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"一张电影感十足的湖畔摄影作品，暮色降临，画面略带俯视角。画面中央，一簇柔和发光的芦苇与睡莲在平静水面上映出金色倒影。优雅的霓虹风白色文字“ai.modelfold.online”悬浮在水面上方，微微发光，与自然光晕和谐融合。四周垂柳与薄雾共同营造出宁静而奇幻的氛围，暖色高光与傍晚天空的冷蓝色形成鲜明对比。\",\"rendering_speed\":\"BALANCED\",\"style\":\"AUTO\",\"expand_prompt\":true,\"image_size\":\"square_hd\",\"seed\":123456,\"negative_prompt\":\"模糊、低清晰度、畸形、额外的肢体、错位文字、水印\"}}",
    "failCode": "500",
    "failMsg": "<error detail>",
    "completeTime": 1786427040000,
    "createTime": 1786426989000,
    "costTime": 48,
    "creditsConsumed": 0,
    "updateTime": 1786427040000
  }
}

Ideogram V3 文生图 ​

接口 ​

创建任务 ​

相关资源 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — 请求成功 ​

500 — 服务器错误 ​

回调 ​

onImageGenerated ​

Ideogram V3 文生图

接口

创建任务

相关资源

请求参数

请求体 (application/json)

请求示例

响应

200 — 请求成功

500 — 服务器错误

回调

onImageGenerated