Ideogram API：接入、端点与图上文字渲染

用代码调用 Ideogram 只需要一个主机名和一个请求头：请求发往 api.ideogram.ai，凭证放在 Api-Key 头里，官方文档没有描述别的鉴权方式。Ideogram 4.0 同时提供同步与异步两种生成方式，同一个账号还能调用编辑端点和单点工具端点。下文出现的每个端点、字段和数字都来自 Ideogram 自己的开发者文档或定价页；官方没公布的地方，这里就写「官方未公布」，不做补全。

官方 API 提供了什么

总览页把能力分成四块：Ideogram 4.0、背景控制、排版，以及自定义模型。它同时写明 4.0 可以从多个入口触达——应用、API 工作流、面向 agent 的 MCP，以及开放权重版本——而这些入口并不等价。API 是按次计费的服务端路径，与任何应用订阅分开结账。要挑模型，Ideogram 4.0 主题页上放着模型层面的口径。

开通接入：官方文档记录的路径

官方记录的接入步骤

四个动作，按顺序：接受开发者条款、添加支付方式、充值、在 API 面板里创建密钥。文档没有描述额外的审批环节，密钥只在创建时完整显示一次。

订阅不支付 API 调用

产品文档用一句话讲清了关系：「Ideogram user subscriptions and API accounts are separate, with separate payment and billing setup.」充值是一次性金额，可选 $20、$50、$100，也可以自定额度，最低 $1、余额上限 $300。应用侧的操作看上手教程，本文所有数字的读取日期是 2026-09-13。

第一条请求：用 Ideogram 4.0 生成

生成是一次 multipart POST。参考文档写明 Content-Type: multipart/form-data，密钥放在 Api-Key 头里，而不是 bearer token。

# 需要 curl 与 jq；先导出 IDEOGRAM_API_KEY。
API="https://api.ideogram.ai/v1/ideogram-v4/generate"

# 一次 multipart POST。密钥是 Api-Key 头，不是 bearer token。
curl -s "${API}" \
  -H "Api-Key: ${IDEOGRAM_API_KEY}" \
  -F 'text_prompt=A poster on a wall with text that reads: "Everything you can imagine is real."' \
  -F "resolution=1024x1024" \
  -F "enable_copyright_detection=false" \
  -o generated.json

# 回复里带 data[].url 和 data[].is_image_safe。链接会过期，
# 所以在同一次运行里把字节取下来。
jq -r '.data[0].is_image_safe' generated.json
curl -sL -o poster.png "$(jq -r '.data[0].url' generated.json)"

响应的结构是 created 加一个 data 数组，数组元素带 prompt、resolution、is_image_safe、seed 和 url。有两个字段决定模型替你解释多少：text_prompt 会自动开启 magic prompt，你写的字符串先被扩写；json_prompt 反过来关掉它，把结构化对象直接喂给扩散模型。参考文档把两者标为互斥。rendering_speed=FLASH 标注为即将上线，目前请求它会返回 400。需要单独处理的错误码是 400、401、422、429。

轮询、落盘与会过期的图片链接

放在队列后面时用异步端点：它立刻返回一个 generation_id，接受可选的 webhook_url 查询参数，结果通过 GET /v1/generations/{generation_id} 轮询取回。

import os
import time

import requests

BASE = "https://api.ideogram.ai/v1"
HEADERS = {"Api-Key": os.environ["IDEOGRAM_API_KEY"]}

# 提交并留下 id：它既是 webhook 的关联键，也是轮询的抓手。
submitted = requests.post(
    f"{BASE}/ideogram-v4/async/generate",
    headers=HEADERS,
    params={"webhook_url": "https://example.com/ideogram-webhook"},
    data={"text_prompt": "A poster for a night market, bold headline at the top."},
    timeout=30,
)
submitted.raise_for_status()
generation_id = submitted.json()["generation_id"]

while True:
    status = requests.get(
        f"{BASE}/generations/{generation_id}", headers=HEADERS, timeout=30
    ).json()
    if status["status"] != "pending":
        break
    time.sleep(5)

if status["status"] == "failed":
    raise SystemExit(status.get("failure_reason", "generation failed"))

# Ideogram 的图片链接会过期，所以现在就把字节存下来。
for index, image in enumerate(status["data"]):
    if not image["is_image_safe"]:
        continue
    with open(f"out-{index}.png", "wb") as handle:
        handle.write(requests.get(image["url"], timeout=60).content)

轮询响应的形状比看上去更严格：任务处于 pending 或 failed 时，报文里只有 generation_id、status 和 created，根本没有 data 这个键。completed 才会补上 response_type 和 data，所以先判 status 再取图。

图片链接是有时限的，产品文档写得很直白：「Image links created by the Ideogram API expire. If you want to keep the image, you must download it and store it.」官方没有公布这条链接的有效期，所以把下载放进同一次运行。Webhook 是可选路径：webhook_url 会在整批图片完成后收到一个 Ed25519 签名的 POST，但官方写明重试次数有限，轮询要留作兜底。

图上文字在 API 上的两种表达

图上文字是 Ideogram 最主要的卖点，API 给了两条路。朴素的一条是在 text_prompt 里写一句带引号的文案：把文字放在提示词前部、用双引号包住、让画面尽量简单。结构化的那条是 json_prompt，它存在的理由官方说得毫不含糊：「Ideogram 4.0 was trained exclusively on structured JSON captions.」

caption schema 要求什么

顶层三个字段。high_level_description 强烈建议填写，style_description 可选，compositional_deconstruction 必需，并且要先写 background、再写 elements。style_description 里必须在 photo 和 art_style 中二选一，同时补上 aesthetics、lighting 和 medium；color_palette 上限是 16 个大写 #RRGGBB。elements 的每一项要么是对象（"obj"），要么是文本元素（"text"）：两者都要写 desc，文本元素多一个 text 字面量，bbox 可选，格式为 [y_min, x_min, y_max, x_max]，归一化到 0–1000。

{
  "high_level_description": "A bold event poster for a jazz night called 'Blue Note Sessions'.",
  "style_description": {
    "aesthetics": "moody, retro, sophisticated",
    "lighting": "dramatic, deep shadows, warm spotlight glow",
    "medium": "graphic_design",
    "art_style": "vintage poster design, textured paper, bold typography",
    "color_palette": ["#1A1A2E", "#E8C97A", "#F5F0E8"]
  },
  "compositional_deconstruction": {
    "background": "Deep navy background with subtle aged paper texture.",
    "elements": [
      {
        "type": "text",
        "bbox": [30, 50, 140, 950],
        "text": "BLUE NOTE SESSIONS",
        "desc": "Large bold all-caps headline in warm golden-yellow near the top."
      },
      {
        "type": "obj",
        "bbox": [150, 200, 650, 800],
        "desc": "A silhouetted jazz trumpeter in side profile, lit from above."
      }
    ]
  }
}

键顺序不是装饰：模型是在键顺序一致的 caption 上训练的，保持顺序能提升质量。同一页还有两条不让步的限制——英文渲染最准，非拉丁文字经常不可预测，而且无法按字体名指定字体。

其余已记录的端点

生成只是其中一部分。编辑端点接收一张图加一段提示词。工具端点按结果命名而不是按模型命名，也不接收 model id，因为 Ideogram 会替每个工具挑模型。自定义模型是一套流程而不是一个开关：建数据集、上传素材、训练，再用得到的模型 URI 生成。价格按端点、按图计，读取日期 2026-09-13：

官方还承诺了一个流程：涉及价格的材料性调整会提前至少 14 天通知现有开发者。旧模型的取值——V_3_1、V_3_0、V_2_1、V_1_5、V_1_1、V_0_3、AUTO——在支持它们的端点上仍然有效。

速率上限，以及官方未公布的边界

官方公布了一个硬数字：默认并发上限是 10 个在途请求，更大规模要走 partnership@ideogram.ai，而那个更大的档位没有任何数字。

• 输出像素。 精确尺寸取决于模型、尺寸档与端点，官方未公布静态像素表。
• 延迟。 参考文档里没有任何按端点分的延迟数据。
• 文字准确率。 官方未公布任何语种的成功率，凡是挂在 Ideogram 排版上的百分比都来自第三方。
• 幂等与有效期。 重试 POST 没有记录去重键；图片链接会过期但没有公布 TTL；webhook 重试次数有限而没给数字。

Nano Banana Pro API 接入示例讲的是同一套轮询与落盘习惯，只是换到图片侧。

第三方网关不是官方 API

搜「ideogram api」还会搜到一批镜像站和网关服务，它们用类似 Ideogram 的名字转售生成能力。有的坦承自己是第三方，有的把自己写成了官方，所以本页的来源只有 ideogram.ai、docs.ideogram.ai 和 developer.ideogram.ai。网关的价格、模型清单和速率上限都是它自己的说法，不是厂商的说法，我们不复述。判断标准很简短：如果 base URL 不是 api.ideogram.ai，上面这些字段就不适用。

常见问题

Ideogram API 密钥怎么拿？ 接受开发者条款、添加支付方式、充值，然后在 API 面板里创建密钥。它只在创建时完整显示一次，关掉页面之前先存进密钥管理服务。

API 包含在 Ideogram 订阅里吗？ 不包含。订阅与 API 账号是分开的，付款和账单也分开。

该传 text_prompt 还是 json_prompt？ 探索阶段用 text_prompt，magic prompt 会替你扩写。需要版式可复现时用 json_prompt，它会关掉 magic prompt，把你写好的结构直接交给模型。

图片链接为什么会突然失效？ 因为这些链接会过期。调用一返回就把字节下载下来；重新生成得到的是另一张图。上手教程讲的是应用侧流程，适合先试模型再写代码。

先用同步调用确认密钥和响应结构，队列成形后再换异步端点加轮询，下载放在产出图片的同一次运行里。这三件事覆盖了官方文档写明的大部分内容，上面列的空白则是要自己绕开的。

发布于

2026年9月13日

信息核验

2026年9月13日

作者

AI Tool Blog 编辑部