Ideogram 3.0 Character API 怎么用？5 分钟跑通第一张角色图

TL;DR

• Ideogram 3.0 Character 是参考图角色生成模型：上传 1 张角色参考图，写一句场景提示词，同一张脸和同一套服饰就出现在新场景里。打开模型页就能在线试，新用户注册送 200 积分。
• 价格按张算：TURBO $0.09、BALANCED $0.13、QUALITY $0.18，参考图不收费，失败不扣费（详见价格页）。
• 调用走 HiAPI /v1/tasks 接口：提交任务拿 taskId，再用它查询结果，成功后从 output[0].url 下载图片。

它能做什么

• 角色一致性生成：一张参考图锁定角色，脸型与服饰保持一致，场景随便换。
• 插画和写实都行：style 可选 AUTO / REALISTIC / FICTION，照片人物和插画角色都吃。
• 画幅跟随参考图：竖版参考出 3:4（864×1152），横版参考出 16:9（1328×752），不用填尺寸参数。
• 配套编辑接口：ideogram-v3-character/edit 用蒙版把角色画进已有图片的指定区域，其余画面不动。

下面这张是真实成品（参考图为一张横版插画角色）：

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

（中文意思：这个探险家角色走在挂满灯笼的夜市里，手里捧着一纸杯热面，两侧是暖光摊位，绘本插画风格，不要文字，不要招牌。）

ideogram-v3-character，TURBO，16:9，1328×752，$0.09。

用这个提示词生成 →

两个接口怎么选

蒙版约定：黑色 = 重绘，白色 = 保留；蒙版和原图宽高比必须一致。编辑接口不接受 negative_prompt，传了会报 400。

两条上手路线

浏览器 3 步：打开模型页 → 上传角色参考图、粘贴提示词 → 点生成，TURBO 一张 $0.09。

API 3 步：POST /v1/tasks 提交 → 拿 taskId → GET /v1/tasks/<taskId> 查到 success 后下载。

curl：第一张

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

编辑接口把 model 换成 ideogram-v3-character/edit，input 里加 image_url（原图）和 mask_url（蒙版）：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

返回里的 taskId 就是查询凭证。

Python：提交、轮询、下载

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# 提交：带 Idempotency-Key，网络重试不会重复建任务
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 轮询：queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

参数表（ideogram-v3-character）

编辑接口在表外多两个必填项 image_url、mask_url，且不支持 negative_prompt。请求体里出现表外字段会直接 400（additional properties ... not allowed）。

你会遇到的报错（接口原文）

同一个 Idempotency-Key 重复提交会返回 409（处理中）或 422（参数不一致），换新 key 再试。

上线前注意

• 回调：请求体顶层传 "callback": {"url": "https://..."}，任务到终态会通知你的服务，省掉轮询。
• 及时转存：output[0].url 是临时地址，拿到就下载存进自己的存储，别把它当永久链接用。
• 显式写档位和画幅：rendering_speed 每次都显式传（不传按 BALANCED 计费）；输出画幅由参考图决定，竖版场景就准备竖版参考图。
• 批量任务各用各的幂等键：每个提交带唯一 Idempotency-Key，网络重试用同一个 key 只会命中同一个任务，不会重复建任务、重复扣积分。

常见问题

• 是的，参考图可以是 URL，只要是能访问的 http/https 地址，JPEG、PNG、WebP 都行，最大 10 MB。
• 是的，参考图只收一张，恰好 1 张是硬性规则，传两张会直接报 400；想换角色就换参考图。
• 不是，不用传尺寸参数，输出画幅跟随参考图：竖版参考出 864×1152，横版参考出 1328×752。
• 是的，两个接口用同一套调用方式，只改 model 和 input 里的字段。
• 不是，失败不扣费，预扣的积分在失败终态后全额退还。

下一步：拿上面的夜市提示词去模型页试一张，然后按场景挑提示词看提示词大全；三档价格和预算表见价格页。