Ideogram Character API 接入文档

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

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

Ideogram 角色编辑

POST/api/v1/jobs/createTask

模型标识： ideogram/character-edit

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该端点必须使用 `ideogram/character-edit` 模型可选值：`"ideogram/character-edit"` 默认：`"ideogram/character-edit"`
`callBackUrl` 可选	`string`	接收生成任务完成通知的回调 URL。可选配置，建议在生产环境中使用。 - 任务生成完成后，系统会向该 URL POST 任务状态与结果 - 回调内容包含生成的资源 URL 与任务相关信息 - 您的回调端点需要支持接收带 JSON 负载的 POST 请求 - 也可以选择调用任务详情端点，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`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.reference_image_urls` 必填	`array`	作为人物参考的图像集合。目前仅支持 1 张图像，其余图像将被忽略。（所有参考图像总大小不超过 10MB）。图像格式需为 JPEG、PNG 或 WebP（为上传后的文件 URL，非文件内容；支持的类型：image/jpeg、image/png、image/webp；最大文件大小：10.0MB） `maxItems: 1`
`input.rendering_speed` 可选	`string`	渲染速度。默认值："BALANCED" 可选值：`"TURBO", "BALANCED", "QUALITY"` 默认：`"BALANCED"`
`input.style` 可选	`string`	生成图像的风格类型。默认值："AUTO" 可选值：`"AUTO", "REALISTIC", "FICTION"` 默认：`"AUTO"`
`input.expand_prompt` 可选	`boolean`	是否启用 MagicPrompt 功能优化生成请求。默认值：true（布尔值：true/false）
`input.num_images` 可选	`string`	生成图像数量可选值：`"1", "2", "3", "4"` 默认：`"1"`
`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/character-edit",
  "input": {
    "prompt": "A fabulous look head tilted down, looking forward with a smile\n",
    "image_url": "https://example.com/input.png",
    "mask_url": "https://example.com/input.png",
    "reference_image_urls": [
      "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.

Ideogram 角色重混

POST/api/v1/jobs/createTask

模型标识： ideogram/character-remix

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该端点必须使用 `ideogram/character-remix` 模型可选值：`"ideogram/character-remix"` 默认：`"ideogram/character-remix"`
`callBackUrl` 可选	`string`	接收生成任务完成通知的回调 URL。可选配置，建议在生产环境中使用。 - 任务生成完成后，系统会向该 URL POST 任务状态与结果 - 回调内容包含生成的资源 URL 与任务相关信息 - 您的回调端点需要支持接收带 JSON 负载的 POST 请求 - 也可以选择调用任务详情端点，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 可选	`object`	生成任务的输入参数
`input.prompt` 必填	`string`	用于图像重混创作的文本提示词（最大长度：5000 字符） `maxLength: 5000`
`input.image_url` 必填	`string`	待重混创作的基础图像 URL。（为上传后的文件 URL，非文件内容；支持的类型：image/jpeg、image/png、image/webp；最大文件大小：10.0MB）
`input.reference_image_urls` 必填	`array`	作为人物参考的图像集合。目前仅支持 1 张图像，其余图像将被忽略。（所有参考图像总大小不超过 10MB）。图像格式需为 JPEG、PNG 或 WebP（为上传后的文件 URL，非文件内容；支持的类型：image/jpeg、image/png、image/webp；最大文件大小：10.0MB） `maxItems: 1`
`input.rendering_speed` 可选	`string`	渲染速度。默认值："BALANCED" 可选值：`"TURBO", "BALANCED", "QUALITY"` 默认：`"BALANCED"`
`input.style` 可选	`string`	生成图像的风格类型。默认值："AUTO" 可选值：`"AUTO", "REALISTIC", "FICTION"` 默认：`"AUTO"`
`input.expand_prompt` 可选	`boolean`	是否启用 MagicPrompt 功能优化生成请求。默认值：true（布尔值：true/false）
`input.image_size` 可选	`string`	生成图像尺寸规格可选值：`"square", "square_hd", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9"` 默认：`"square_hd"`
`input.num_images` 可选	`string`	生成图像数量可选值：`"1", "2", "3", "4"` 默认：`"1"`
`input.seed` 可选	`integer`	随机数生成器的种子值
`input.strength` 可选	`number`	基础图像在重混创作中的影响力权重。默认值：0.8（最小值：0.1，最大值：1，步长：0.1）默认：`0.8` `minimum: 0.1` `maximum: 1`
`input.negative_prompt` 可选	`string`	需从生成图像中排除的内容描述。提示词中的描述优先级高于反向提示词。默认值：""（最大长度：500 字符） `maxLength: 500`
`input.image_urls` 可选	`array`	作为风格参考的图像集合（所有风格参考图像总大小不超过 10MB）。图像格式需为 JPEG、PNG 或 WebP（为上传后的文件 URL，非文件内容；支持的类型：image/jpeg、image/png、image/webp；最大文件大小：10.0MB） `maxItems: 5`
`input.reference_mask_urls` 可选	`string`	应用于人物参考图像的蒙版集合。目前仅支持 1 张蒙版，其余蒙版将被忽略。（所有人物参考蒙版总大小不超过 10MB）。蒙版格式需为 JPEG、PNG 或 WebP（为上传后的文件 URL，非文件内容；支持的类型：image/jpeg、image/png、image/webp；最大文件大小：10.0MB）

请求示例

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/character-remix",
  "input": {
    "prompt": "A fisheye lens selfie photograph taken at night on an urban street. The image is circular with a black border and shows a person wearing dark sunglasses and a black jacket, holding a silver digital camera up to capture the reflection. The background shows a row of shuttered storefronts with red neon lighting visible in the upper portion. The street is empty and dark, with street lights creating a warm glow along the sidewalk. The fisheye effect creates a curved, distorted perspective that bends the straight lines of the street and buildings. The lighting is predominantly red and dark, creating a moody urban atmosphere. The person'\''s reflection shows long dark hair and is positioned in the center of the circular frame. Multiple storefront shutters are visible in the background, creating a repeating pattern of horizontal lines. The overall composition has a cinematic quality with strong contrast between the dark street and the illuminated storefronts above.",
    "image_url": "https://example.com/input.png",
    "reference_image_urls": [
      "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.

Ideogram 角色图像生成

POST/api/v1/jobs/createTask

模型标识： ideogram/character

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该端点必须使用 `ideogram/character` 模型可选值：`"ideogram/character"` 默认：`"ideogram/character"`
`callBackUrl` 可选	`string`	接收生成任务完成通知的回调 URL。可选配置，建议在生产环境中使用。 - 任务生成完成后，系统会向该 URL POST 任务状态与结果 - 回调内容包含生成的资源 URL 与任务相关信息 - 您的回调端点需要支持接收带 JSON 负载的 POST 请求 - 也可以选择调用任务详情端点，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 可选	`object`	生成任务的输入参数
`input.prompt` 必填	`string`	描述要生成的画面（使用参考角色）的提示词。（最大长度：5000 字符） `maxLength: 5000`
`input.reference_image_urls` 必填	`array`	作为人物参考的图像集合。目前仅支持 1 张图像，其余图像将被忽略。（所有参考图像总大小不超过 10MB）。图像格式需为 JPEG、PNG 或 WebP（为上传后的文件 URL，非文件内容；支持的类型：image/jpeg、image/png、image/webp；最大文件大小：10.0MB） `maxItems: 1`
`input.rendering_speed` 可选	`string`	渲染速度。默认值："BALANCED" 可选值：`"TURBO", "BALANCED", "QUALITY"` 默认：`"BALANCED"`
`input.style` 可选	`string`	生成图像的风格类型。默认值："AUTO" 可选值：`"AUTO", "REALISTIC", "FICTION"` 默认：`"AUTO"`
`input.expand_prompt` 可选	`boolean`	是否启用 MagicPrompt 功能优化生成请求。默认值：true（布尔值：true/false）
`input.num_images` 可选	`string`	生成图像数量可选值：`"1", "2", "3", "4"` 默认：`"1"`
`input.image_size` 可选	`string`	生成图像的分辨率规格。默认值：square_hd 可选值：`"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 字符） `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/character",
  "input": {
    "prompt": "Place the woman from the uploaded portrait, wearing a casual white blouse, in a peaceful garden setting. The scene should feature vibrant green plants and colorful flowers, with soft sunlight filtering through the leaves. She should be sitting on a wooden bench, holding a book and smiling gently. The background should be filled with lush greenery, with a serene, tranquil atmosphere. Golden afternoon light should highlight the woman’s face and create soft shadows on the ground, adding a peaceful, reflective mood to the scene",
    "reference_image_urls": [
      "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.

任务状态与回调

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

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

文件、日志与计费

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

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