
这份 Ideogram 4.6 API 指南带你从 API key 一路走到用 cURL 和 Python 拿到成品图,然后介绍 PoYo schema 接受的每一种输入模式:预设或自定义尺寸的文生图、透明背景、普通编辑、蒙版编辑、参考图和高精度编辑。文生图使用模型 ID ideogram-v4.6,编辑使用 ideogram-v4.6-edit;两者都列在 Ideogram 4.6 模型页面上。
字段规则来自 PoYo API 参考。想了解这个模型是什么以及与其他模型的对比,请先阅读 Ideogram 4.6 API 概览。
第 1 步:用 cURL 提交 Ideogram 4.6 API 请求
在 PoYo 控制台创建一个 key,并导出为 POYO_API_KEY。把它放在服务端,不要放进浏览器代码。
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.6",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}'
这里使用默认值:size: auto(约 2K)、quality: medium、一张图,因此费用为 12 积分($0.06)。提交成功会返回 code: 200 和一个 data 对象,其中包含 task_id、status: "not_started" 和 created_time。这是一个排队中的任务,还不是图像。每次都要检查响应体中的 code:部分校验错误会以 HTTP 200 和 code: 400 返回。
第 2 步:轮询任务状态
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
状态依次经过 not_started、running,然后是 finished 或 failed。已完成的任务会在 data.files 中为每张图列出一项,每项包含 file_url 和 file_type: "image",并在 credits_amount 中报告扣费。失败的任务会在 error_message 中说明原因。
第 3 步:有超时上限的 Python 轮询循环
这个循环同时检查 HTTP 状态和响应体中的 code,遇到 failed 时停止,在 n 大于 1 时返回所有图像,并在 10 分钟后放弃,且不会重新提交。
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def run(model, input_body, max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images, task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
images, credits = run("ideogram-v4.6", {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "1728x2304",
"quality": "high",
"n": 2,
})
print(images, credits)
1728x2304 是一个 3:4 尺寸,共 3,981,312 像素,低于 4,194,304 像素的分界线,因此两张图都按 2K high 费率计费:2 × 20 = 40 积分($0.20)。超时的意思是“稍后再查询同一个任务 ID”。重新提交会启动第二个计费任务。同一个 run() 也适用于编辑:把模型传为 "ideogram-v4.6-edit" 即可。
Ideogram 4.6 API 的所有输入模式
所有字段都放在 input 内。模型 ID 和可选的 callback_url 位于顶层。
4K 文生图
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 是 6,291,456 像素,超过 4,194,304,因此属于 4K 档,并且在此尺寸下不允许使用 very_low。
透明背景与固定 seed
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
transparent 返回带 alpha 通道的图像;opaque 强制使用纯色背景。用相同的 seed 发送相同的请求体即可复现结果。
普通编辑
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
普通编辑会根据提示词重新生成图像。image_urls 必须是只含一张图的数组,使用公开的 HTTP(S) URL 或 base64 data URI。要发送本地文件,请先用 PoYo 的文件上传接口上传。
参照参考图改换风格
{
"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
}
}
最多允许 4 张参考图,带蒙版时为 3 张。这里允许自定义 size,因为这是不带蒙版的普通编辑。
整图高精度编辑
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high"
}
}
这是我们发布当天那次编辑的请求体(任务 672JRU198S22NS8D,2026 年 11 月 20 日),只替换了源图 URL。源图是一张 2304×3072 的海报;输出保持该尺寸,只改动了日期行,任务扣费 120 积分($0.60),即 4K high 编辑费率。
局部蒙版编辑
{
"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"
}
}
蒙版必须与源图尺寸一致,并同时包含黑色(编辑)和白色(保留)区域。使用 context_window: auto 时,只有蒙版周围的区域会以源图分辨率被编辑。蒙版过大时会退回到整图编辑。
字段校验规则
在提交前先在你这边校验,让错误请求尽早失败:
| 字段 | 规则 |
|---|---|
model | ideogram-v4.6 或 ideogram-v4.6-edit |
prompt | 必填,1 到 10,000 个字符,不能只有空白 |
size | auto、1:1、1:1 HD、4:3、3:4、16:9、9:16,或使用小写 x 的 WIDTHxHEIGHT |
| 自定义尺寸 | 每边 256 到 4096 且为 32 的倍数;宽高比在 1:6 到 6:1 之间 |
quality | 仅当输出不超过 4,194,304 像素时可用 very_low |
n | 整数 1 到 8;字符串和布尔值会被拒绝 |
image_urls | 仅限编辑;只含一张图的数组 |
mask_url、edit_precision: high | 需要 size: auto(或不传 size) |
background | 当 edit_precision 为 high 时会被拒绝 |
context_window: auto | 需要 mask_url 和 edit_precision: high |
| 未知字段 | 被拒绝,返回 unsupported fields 错误 |
示例:2304x3072 可以通过(两边都是 32 的倍数);1296x3168 会失败,因为 1296 不是 32 的倍数,即使 Ideogram 4.5 接受它;4096x512 会失败(比例 8:1);2048x3072 下使用 very_low 会失败。
值得处理的错误
code | 含义 | 处理方式 |
|---|---|---|
| 400 | 参数无效 | 修正请求体;不要原样重试 |
| 401 | API key 缺失或无效 | 检查 Authorization: Bearer 请求头 |
| 402 | 积分不足 | 充值后重新提交 |
| 429 | 超出速率限制 | 退避后稍后重试 |
| 500, 502, 503 | 服务端、上游或可用性错误 | 带退避重试;先检查是否已经返回了任务 ID |
进入 failed 的任务会在 error_message 中给出原因。完整列表见错误码。
用回调代替轮询
在请求体顶层(而不是 input 内)添加 "callback_url": "https://your-app.example.com/poyo-webhook"。任务完成或失败时,PoYo 会向该 URL POST 任务数据,并在 X-Webhook-Signature 请求头中用 HMAC-SHA256 签名;webhook 文档给出了签名规则。对于始终没有到达的回调,保留一个低频轮询作为兜底。
你的第一笔账单是怎么算的
Ideogram 4.6 API 按输出图像计费:质量与尺寸档位的价格 × n。1 积分 = $0.005。
| 请求 | 档位 | 费用 |
|---|---|---|
默认值(auto、medium、n: 1) | 文生图 medium 2K | 12 积分($0.06) |
very_low、3:4、n: 1 | 文生图 very_low 2K | 1.6 积分($0.008) |
high、1728x2304、n: 2 | 文生图 high 2K | 40 积分($0.20) |
high、2304x3072、n: 1 | 文生图 high 4K | 40 积分($0.20) |
对 2304×3072 源图做高精度编辑,high | 编辑 high 4K | 120 积分($0.60) |
very_low 和 2304x3072 两行与我们发布当天任务的实际扣费一致。对于 size: auto 的编辑,价格按源图尺寸报价,按交付的图像结算,绝不会高于报价。价格文章中有更多计算示例。
常见问题
Ideogram 4.6 API 兼容 OpenAI SDK 吗?
不兼容。它是异步任务 API:提交到 /api/generate/submit,然后轮询 /api/generate/status/{task_id} 或接收回调。直接用 requests、fetch 或 cURL 即可。
如何用 Ideogram 4.6 API 编辑图像?
调用 ideogram-v4.6-edit,在 image_urls 中放一个 URL,在 prompt 中写明修改内容。添加 edit_precision: high 可以保留你没有要求修改的像素。
可以给 ideogram-v4.6 发送参考图吗?
不可以。在 PoYo 上,参考图放在 ideogram-v4.6-edit 的 reference_image_urls 中,最多 4 张,带蒙版时为 3 张。
一次 Ideogram 4.6 API 请求返回多少张图?
1 到 8 张,由 n 设置。每张图都按档位价格计费。
为什么我的 Ideogram 4.6 API 请求因尺寸被拒绝?
自定义边长必须是 256 到 4096 之间 32 的倍数,并且蒙版或高精度编辑需要 size: auto。