how-tos

Ideogram 4.6 API 指南:用 cURL 和 Python 生成第一张图并完成编辑

Poyo.ai Team
5 min read
Share:

使用 cURL 和 Python 的 Ideogram 4.6 API 指南

这份 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 时,只有蒙版周围的区域会以源图分辨率被编辑。蒙版过大时会退回到整图编辑。

字段校验规则

在提交前先在你这边校验,让错误请求尽早失败:

字段规则
modelideogram-v4.6 或 ideogram-v4.6-edit
prompt必填,1 到 10,000 个字符,不能只有空白
sizeauto、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参数无效修正请求体;不要原样重试
401API 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 2K12 积分($0.06)
very_low、3:4、n: 1文生图 very_low 2K1.6 积分($0.008)
high、1728x2304、n: 2文生图 high 2K40 积分($0.20)
high、2304x3072、n: 1文生图 high 4K40 积分($0.20)
对 2304×3072 源图做高精度编辑,high编辑 high 4K120 积分($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。

Share: