curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "ideogram-v4.6-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
'
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2026-10-13T10:30:00+08:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}Ideogram
Ideogram V4.6 Edit
Ideogram 4.6 Edit API 根据文本提示词编辑一张源图,支持可选蒙版、最多四张参考图、常规或高精度编辑,以及保留原始分辨率的局部编辑。
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "ideogram-v4.6-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
'
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2026-10-13T10:30:00+08:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}- 提交后会返回
task_id。如果提供了callback_url,当任务状态变为finished或failed时,系统会向callback_url发送 POST 请求。 - 无论是否提供
callback_url,都可以通过统一的查询任务状态接口获取结果。
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 张结果,常规编辑支持透明背景,并可用种子复现结果。
编辑模式
| 模式 | 设置 | 效果 |
|---|---|---|
| 常规编辑(默认) | edit_precision: regular | 根据提示词重新生成图像。不使用蒙版时,可通过 size 改变输出尺寸。支持 background。 |
| 高精度编辑 | edit_precision: high、context_window: none | 对整张图进行精确编辑,并还原未改动的像素。输出保留原始分辨率。 |
| 局部编辑 | edit_precision: high、context_window: auto、mask_url | 只编辑蒙版周围的区域,保留原始分辨率和该区域之外的所有像素。蒙版过大时会退回整图编辑。 |
必填参数
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。
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。
编辑图像
{
"model": "ideogram-v4.6-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
局部蒙版编辑
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
参考图风格迁移
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Restyle the product shot to match the reference",
"image_urls": [
"https://example.com/product.png"
],
"reference_image_urls": [
"https://example.com/style.png"
],
"size": "2048x2048",
"quality": "low",
"n": 2
}
}
注意事项
- 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,请通过查询任务状态获取编辑后的图像。
授权
所有 API 接口都需要 Bearer Token 认证。
创建 API Key:登录 PoYo,进入 仪表盘 → API 密钥(poyo.ai/zh/dashboard/api-key),点击创建 Key。
在请求头中添加:
Authorization: Bearer YOUR_API_KEY
请求体
application/json
响应
任务提交成功
业务状态码。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