Ideogram 4.5 API 怎么用？生成、编辑和任务查询

TL;DR

• Ideogram 4.5 是文字排版优先的文生图系列：ideogram-v4.5/text-to-image 生成海报、Logo 字标、双语包装这类带文字的画面，ideogram-v4.5/image-to-image 用 Precise Edit 精准改字、参考图换风格、蒙版改局部。可从模型页选择任务，也可按下文调用接口。
• 价格按张算、随质量档变：LOW $0.043、MEDIUM（默认）$0.086、HIGH $0.3145；编辑档 VERY_LOW $0.0115 起；当前每次请求出 1 张，num_images 只能为 1。详见价格页。
• 调用走 HiAPI /v1/tasks 接口：提交后读取 data.taskId，再查询 data.status；成功后从 data.output 取 type=image 的地址下载。

它能做什么

• 组织画面文字层级：把需要出现的文字放进引号，分别说明标题、副标题、日期和阵容的位置；出图后逐字检查。
• 单张任务探索构图：每个请求出 1 张；调整提示词或 seed，分别提交多个任务比较方向。
• 配套编辑接口：Precise Edit（edit_precision=high）可用于品牌名、日期等小范围修改；对照源图检查保留区域。
• 参考图 + 蒙版：参考图最多 4 张（带蒙版时 3 张）；蒙版黑色 = 重绘、白色 = 保留。

下面是生成的真实成品（LOW 档）：

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

（中文意思：极简现代的设计大会品牌海报，居中超大粗体标题 "DESIGN FORWARD"，下方小字副标题 "Typography Summit 2026"，瑞士网格版式，暖橙与深海军蓝配色，几何图形，字母锐利清晰。尺寸选 landscape_16_9。）

ideogram-v4.5/text-to-image，LOW，landscape_16_9，1280×720，$0.043。

用这个提示词生成 →

两个接口怎么选

典型流水线：生成出品牌海报，再用 Edit 把品牌名或日期改成客户的版本。生成 LOW 一张 $0.043 加 Precise LOW 改一次字 $0.043，一套 $0.086。

两条上手路线

浏览器 3 步：打开模型页 → 粘贴提示词、选质量档 → 点生成。

API 3 步：POST /v1/tasks 提交 → 读取 data.taskId → GET /v1/tasks/<taskId> 查询 data.status，到 success 后下载。

curl：第一张

先在终端设置 HIAPI_IDEMPOTENCY_KEY 为本次业务的唯一标识，重试相同请求时沿用该值。示例显式使用LOW、横版尺寸和开启扩写。

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

编辑接口：model 换 ideogram-v4.5/image-to-image，传源图和指令。下面用Precise Edit提出改字及保留布局的要求，成品仍需对照源图检查：

该编辑任务另外设置 HIAPI_EDIT_IDEMPOTENCY_KEY，不要复用生成任务的键。

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

Python：提交、轮询、下载

先安装 requests，设置 HIAPI_API_KEY；首次提交还需设置 HIAPI_IDEMPOTENCY_KEY，每个新业务使用独立值，同一次提交重试保持不变。程序会先打印任务ID；中断后设置 HIAPI_TASK_ID 可继续查询和下载，不会再次提交生成。

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

查询或下载遇到网络错误时，保留已打印的任务ID再恢复；脚本不自动重发创建请求。示例轮询上限为600秒，每次等待3秒，下载先写 .part 文件，完成后才改为正式文件名。

参数表

生成 ideogram-v4.5/text-to-image

编辑 ideogram-v4.5/image-to-image

input 内出现该模型参数表以外的字段会返回 400；顶层 model、callback 等按任务接口格式填写。

你会遇到的报错

任务终态失败可能包含 CONTENT_POLICY_VIOLATION、TASK_FAILED、TASK_TIMEOUT 等错误码。保留 taskId 和错误信息，结合任务最终状态与账户记录核对结算；不要把查询失败或下载失败当成生成失败。

上线前注意

• 回调：请求体顶层传 "callback": {"url": "https://..."}，终态自动通知。
• 及时转存：data.output 中的结果链接有有效期，成功后及时下载。
• 单张任务与幂等：每次出 1 张；同一业务请求因超时而重试时沿用原幂等键，新业务任务才使用新键。
• 中文小字：按实际文案比较质量档；交付前逐字校对，medium或high也不能代替检查。

常见问题

一次请求最多生成几张？

当前生成和编辑每次都输出 1 张，num_images 只能为 1。多个方向分别提交任务。

默认质量档是 LOW 吗？

不是。默认是 MEDIUM，每张 $0.086；需要 LOW 每张 $0.043 时显式传 quality: "low"。

只换品牌名和日期用什么模式？

可选 Precise Edit，显式传 edit_precision: "high"、quality: "low"、image_size: "auto"；每张 $0.043。

蒙版的黑白区域分别代表什么？

黑色区域重绘，白色区域保留。蒙版与源图同尺寸，使用蒙版时 image_size 选 auto。

提交超时后要换幂等键吗？

同一业务请求重试不要换键，沿用相同 Idempotency-Key 和相同请求体；确实需要新任务时才使用新键。

下一步：拿 DESIGN FORWARD 海报提示词去模型页出一张，再用一句 Precise 指令把标题换成你自己的活动名。 配套阅读：三档价格与预算 · 4 个编辑提示词案例。