Ideogram V3 API 接入文档

使用 VezAPI 密钥接入 Ideogram V3。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

Ideogram V3 混合

POST/api/v1/jobs/createTask

模型标识： ideogram/v3-remix

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该端点必须使用 `ideogram/v3-remix` 模型可选值：`"ideogram/v3-remix"` 默认：`"ideogram/v3-remix"`
`callBackUrl` 可选	`string`	接收任务完成通知的回调 URL。可选参数；如果提供，系统会在任务完成（成功或失败）后向该地址发送 POST 请求；如未提供，则不会发送回调通知。
`input` 必填	`object`	图像重绘任务的输入参数。
`input.prompt` 必填	`string`	用于重绘图像的提示词（最大长度：5000 字符）。 `maxLength: 5000`
`input.image_url` 必填	`string`	用于重绘的图像 URL。 - 请提供上传后文件的 URL，而非文件内容 - 支持类型：`image/jpeg`、`image/png`、`image/webp` - 最大文件大小：10.0MB
`input.rendering_speed` 可选	`string`	生成时使用的渲染速度。 - `TURBO`: 极速 - `BALANCED`: 均衡 - `QUALITY`: 高质量可选值：`"TURBO", "BALANCED", "QUALITY"`
`input.style` 可选	`string`	生成时使用的风格类型。 - `AUTO`: 自动 - `GENERAL`: 通用 - `REALISTIC`: 写实 - `DESIGN`: 设计可选值：`"AUTO", "GENERAL", "REALISTIC", "DESIGN"`
`input.expand_prompt` 可选	`boolean`	是否在生成请求中启用 MagicPrompt。 - 布尔值：`true` / `false`
`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"`
`input.num_images` 可选	`string`	生成图像数量。 - `1`: 1 张 - `2`: 2 张 - `3`: 3 张 - `4`: 4 张可选值：`"1", "2", "3", "4"`
`input.seed` 可选	`integer`	随机数生成器的种子值。
`input.strength` 可选	`number`	输入图像在重绘中的影响强度。 - 最小值：`0.01` - 最大值：`1` - 步长：`0.01` `minimum: 0.01` `maximum: 1`
`input.negative_prompt` 可选	`string`	描述图像中需要排除的内容。若正向提示词与负向提示词冲突，以正向提示词为准。最大长度：5000 字符。 `maxLength: 5000`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "ideogram/v3-remix",
  "input": {
    "prompt": "Change the cube into a sphere",
    "image_url": "https://example.com/input.png"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	Response message, error description upon failure
`data` 必填	`object`
`data.taskId` 必填	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

HTTP 500

服务器错误

Ideogram V3 图像编辑

POST/api/v1/jobs/createTask

模型标识： ideogram/v3-edit

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该端点必须使用 `ideogram/v3-edit` 模型可选值：`"ideogram/v3-edit"` 默认：`"ideogram/v3-edit"`
`callBackUrl` 可选	`string`	接收任务完成通知的回调 URL。可选参数；如果提供，系统会在任务完成（成功或失败）后向该地址发送 POST 请求；如未提供，则不会发送回调通知。
`input` 必填	`object`	图像编辑任务的输入参数。
`input.prompt` 必填	`string`	用于填充图像蒙版区域的文本提示词（最大长度：5000 字符）。 `maxLength: 5000`
`input.image_url` 必填	`string`	用于生成的原始图像 URL。需要与蒙版图像尺寸一致。 - 请提供上传后文件的 URL，而非文件内容 - 支持类型：`image/jpeg`、`image/png`、`image/webp` - 最大文件大小：10.0MB
`input.mask_url` 必填	`string`	用于图像修复的蒙版 URL。需要与输入图像尺寸一致。 - 请提供上传后文件的 URL，而非文件内容 - 支持类型：`image/jpeg`、`image/png`、`image/webp` - 最大文件大小：10.0MB
`input.rendering_speed` 可选	`string`	生成时使用的渲染速度。默认值：`BALANCED`。 - `TURBO`: 极速 - `BALANCED`: 均衡 - `QUALITY`: 高质量可选值：`"TURBO", "BALANCED", "QUALITY"` 默认：`"BALANCED"`
`input.expand_prompt` 可选	`boolean`	是否在生成请求中启用 MagicPrompt。默认值：`true`。 - 布尔值：`true` / `false` 默认：`true`
`input.seed` 可选	`integer`	随机数生成器的种子值。

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "ideogram/v3-edit",
  "input": {
    "prompt": "A dog wearing a cowboy hat",
    "image_url": "https://example.com/input.png",
    "mask_url": "https://example.com/input.png"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	Response message, error description upon failure
`data` 必填	`object`
`data.taskId` 必填	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

HTTP 500

服务器错误

Ideogram V3 文生图

POST/api/v1/jobs/createTask

模型标识： ideogram/v3-text-to-image

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该端点必须使用 `ideogram/v3-text-to-image` 模型可选值：`"ideogram/v3-text-to-image"` 默认：`"ideogram/v3-text-to-image"`
`callBackUrl` 可选	`string`	接收任务完成通知的回调 URL。可选参数；如果提供，系统会在任务完成（成功或失败）后向该地址发送 POST 请求；如未提供，则不会发送回调通知。
`input` 必填	`object`	生成任务的输入参数。
`input.prompt` 必填	`string`	要生成图像的描述文本（最大长度：5000 字符）。 `maxLength: 5000`
`input.rendering_speed` 可选	`string`	生成时使用的渲染速度。 - `TURBO`: 极速 - `BALANCED`: 均衡 - `QUALITY`: 高质量可选值：`"TURBO", "BALANCED", "QUALITY"`
`input.style` 可选	`string`	生成时使用的风格类型。 - `AUTO`: 自动 - `GENERAL`: 通用 - `REALISTIC`: 写实 - `DESIGN`: 设计可选值：`"AUTO", "GENERAL", "REALISTIC", "DESIGN"`
`input.expand_prompt` 可选	`boolean`	是否在生成请求中启用 MagicPrompt。 - 布尔值：`true` / `false`
`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"`
`input.seed` 可选	`integer`	随机数生成器的种子值。
`input.negative_prompt` 可选	`string`	描述图像中需要排除的内容。若正向提示词与负向提示词冲突，以正向提示词为准。最大长度：5000 字符。 `maxLength: 5000`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "ideogram/v3-text-to-image",
  "input": {
    "prompt": "A cinematic photograph of a tranquil lakeside at twilight, viewed from a slight elevation. In the center, a cluster of softly glowing reeds and water lilies emit a gentle golden light, their reflections shimmering on the calm surface. The elegant neon-style white text '\''Kie.ai'\'' hovers just above the water, subtly illuminated and harmonizing with the natural glow. Surrounding willows and drifting mist frame the scene, creating a serene yet magical atmosphere, with warm highlights contrasting against the cool blues of the evening sky."
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	Response message, error description upon failure
`data` 必填	`object`
`data.taskId` 必填	`string`	The task ID can be used with the "Get Task Details" endpoint to query the task status.

HTTP 500

服务器错误

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。