跳转到主要内容
POST
  1. 提交后会返回 task_id。如果提供了 callback_url,当任务状态变为 finished 或 failed 时,系统会向 callback_url 发送 POST 请求。
  2. 无论是否提供 callback_url,都可以通过统一的查询任务状态接口获取结果。
Ideogram 4.6 Edit API 是 Ideogram 4.6 API 的图像编辑模型。传入一张源图和提示词,即可替换背景、修改招牌上的文字、重新设计产品图风格,或只重绘蒙版标出的区域。参考图可以引导风格或内容,高精度编辑会还原所有未要求修改的像素。如果只想根据提示词生成图像,请使用 Ideogram 4.6 API 文生图模型。

Ideogram 4.6 API 模型

  • ideogram-v4.6-edit — 编辑恰好一张源图,可选蒙版、参考图和精度控制
  • ideogram-v4.6 — 文生图。参见 Ideogram V4.6

Ideogram 4.6 Edit API 功能

  • 提示词编辑:用自然语言描述要做的修改。需要原样出现在图上的文字,请用引号括起来。
  • 蒙版编辑:蒙版中黑色区域会被编辑,白色区域保持不变。
  • 参考图:最多添加四张参考图,设置蒙版时最多三张。
  • 高精度编辑:edit_precision: high 进行精确编辑,并还原未改动的像素。
  • 保留完整分辨率的局部编辑:设置 context_window: auto 时,Ideogram 4.6 Edit API 只编辑蒙版周围的区域,并保留源图分辨率。
  • 批量、背景与种子:每次请求最多输出 8 张结果,常规编辑支持透明背景,并可用种子复现结果。

编辑模式

必填参数

  • prompt (string):描述修改内容的提示词,1–10,000 个字符,必须包含非空白文本。
  • image_urls (array of strings):恰好一张源图。使用公开的 HTTP(S) 图像 URL 或 base64 图像 data URI(data:image/<type>;base64,...)。即使只有一张图,也必须传数组。

可选参数

  • mask_url (string):与源图尺寸相同的蒙版图。黑色区域会被编辑,白色区域保持不变,蒙版必须同时包含两者。可使用公开的 HTTP(S) URL 或 base64 图像 data URI。要求 size 为 auto。
  • reference_image_urls (array of strings):0 到 4 张参考图,设置 mask_url 时最多 3 张。可使用公开的 HTTP(S) URL 或 base64 图像 data URI。
  • edit_precision (string):regular 或 high。默认为 regular。regular 重新生成图像;high 进行精确编辑并还原未改动的像素。high 要求 size 为 auto。
  • context_window (string):none 或 auto。默认为 none。auto 要求 edit_precision: high 并提供 mask_url。参见编辑模式。
  • size (string):auto、1:1、1:1 HD、4:3、3:4、16:9、9:16 或自定义 WIDTHxHEIGHT。默认为 auto,保留源图的几何尺寸。参见尺寸。
  • quality (string):very_low、low、medium 或 high。默认为 medium。very_low 只适用于不超过 4,194,304 像素的输出。
  • background (string):transparent 或 opaque。仅限常规编辑;edit_precision 为 high 时会被拒绝。
  • n (integer):结果数量,1 到 8。默认为 1。
  • seed (integer):随机种子,0 到 2147483647。不传则自动选取。
  • callback_url (string):可选的 Webhook URL,用于任务完成通知。放在请求顶层,不要放进 input。
Ideogram 4.6 Edit API 的 input 只接受以上字段。传入其他字段会返回 unsupported fields 错误。

尺寸

  • auto(默认)保留源图的几何尺寸。在 Ideogram 4.6 Edit API 中,使用 mask_url 或 edit_precision: high 时只能用 auto,否则请求会失败,错误信息为 “mask_url or high edit_precision requires size auto”。
  • 不使用蒙版的常规编辑还可以使用预设 1:1(512×512)、1:1 HD(1024×1024)、4:3(1024×768)、3:4(768×1024)、16:9(1024×576)和 9:16(576×1024)。
  • 自定义 WIDTHxHEIGHT 尺寸使用小写 x。宽和高都必须在 256 到 4096 像素之间且为 32 的倍数,宽高比须在 1:6 到 6:1 之间。

输出

Ideogram 4.6 Edit API 任务状态为 finished 时,files 中每张编辑后的图像对应一项,包含 file_url 和 file_type: image。

Ideogram 4.6 Edit API 示例

将下面的 Ideogram 4.6 Edit API 请求发送到 POST /api/generate/submit,并在 Authorization 请求头中携带 API Key。

编辑图像

局部蒙版编辑

只编辑蒙版黑色部分周围的区域,并保留原始分辨率。

参考图风格迁移

注意事项

  • Ideogram 4.6 Edit API 要求 image_urls 中恰好包含一张源图。
  • context_window: auto 未同时设置 edit_precision: high 和 mask_url 时会被拒绝。
  • very_low 与超过 4,194,304 像素的自定义尺寸同时使用时会被拒绝。
  • 源图、蒙版和参考图可以是公开的 HTTP(S) URL 或 base64 图像 data URI。如需使用本地文件,也可以先通过文件管理上传。
  • 生成的图像文件在创建后 3 天内可访问,请及时下载保存。
  • 响应返回 task_id,请通过查询任务状态获取编辑后的图像。

授权

Authorization
string
header
必填

所有 API 接口都需要 Bearer Token 认证。

创建 API Key:登录 PoYo,进入 仪表盘 → API 密钥(poyo.ai/zh/dashboard/api-key),点击创建 Key。

在请求头中添加:

请求体

application/json
model
enum<string>
必填

Ideogram 4.6 Edit 模型标识。

可用选项:
ideogram-v4.6-edit
input
object
必填

编辑恰好一张源图。

callback_url
string<uri>

可选的 Webhook URL,任务完成或失败时通知。

响应

任务提交成功

code
enum<integer>
必填

业务状态码。200 表示成功,其他值都表示请求失败。请务必检查这个字段:部分参数校验错误会以 HTTP 200 返回,响应体里的 code 为 400。

  • 200:成功
  • 400:请求参数无效
  • 401:API Key 缺失或无效
  • 402:积分不足
  • 403:没有权限
  • 404:资源不存在
  • 408:请求超时
  • 429:请求频率超限
  • 500:服务器内部错误
  • 502:上游服务错误
  • 503:服务暂不可用

详见错误码。

可用选项:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
示例:

200

data
object
必填