博客

教程

如何通过 HiAPI API 使用 ideogram-v3-character：curl + Python 指南

在 HiAPI 上进行角色一致性图像生成的请求优先实战演练

2026年10月31日

ideogram-v3-character 是什么，以及何时使用它

ideogram-v3-character 是 HiAPI 上专注于角色一致性的图像生成模型。它不会把每次生成都当作独立提示词处理，而是允许你提供角色的参考图像，使后续渲染保持相同的面部、服装和整体身份特征。

当是谁和做什么同样重要时，就该使用它：

故事板和漫画：同一角色出现在多个分镜中。
游戏素材变体：为一个主角角色生成不同姿势、表情或服装。
品牌吉祥物：必须在许多不同场景和背景中保持形象一致。
迭代式美术指导：在多轮调整中精修角色，同时不丢失相似度。

如果你只需要一次性插图，并且不在乎匹配之前的图像，通用文生图模型更简单。参考图像带来的额外结构，正是 ideogram-v3-character 值得增加请求字段的原因。

该模型与其他模型一样，通过统一的 HiAPI 图像生成端点对外暴露，因此请求结构会让人感到熟悉：你发送 JSON 负载，接收异步任务的作业引用，并轮询直到结果就绪。本教程重点讲如何正确完成这个流程。

发送请求之前：设置与身份验证

首次调用前，你只需要准备好几件事。

1. API 密钥

在 HiAPI 账户仪表板中创建 API 密钥。请将其视为机密——它为你的每个请求授权，并计入你的账户账单。

2. 基于环境变量的凭据处理

切勿将密钥硬编码在源文件中，也不要提交到 git。请改用环境变量：

export HIAPI_API_KEY="your_api_key_here"

在 Python 中，你可以这样读取它：

import os
api_key = os.environ["HIAPI_API_KEY"]

如果你在本地开发中使用 .env 文件，请在做其他任何事情之前先将其加入 .gitignore。

3. 参考图像 URL

由于角色一致性依赖参考图，请准备一张可通过 URL 传入的图像。确保该 URL 可公开访问，或以其他方式可被 API 访问——位于身份验证之后的私有链接会失败。正方形或竖版、能清晰展示角色面部的图像效果最佳。

4. 发起 HTTP 请求的方式

命令行中的 curl，或安装了 requests 的 Python 环境，任意一种都足够。下面的示例假设你具备其中之一。

准备好这四项后，你就可以发送第一个请求了。

逐行解析一个可用的 curl 请求

下面是一个向 HiAPI 提交 ideogram-v3-character 作业的完整请求。请将占位符替换为你自己的值。

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "一位友好的机器人机械师站在阳光充足的工作坊里，手持扳手，四分之三视角",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

各部分的作用

POST /v1/images/generations — 统一的 HiAPI 图像生成端点。所有模型都走同一路径。
Authorization: Bearer $HIAPI_API_KEY — 对调用进行身份验证。shell 会展开你之前设置的环境变量。
Content-Type: application/json — 你发送的是 JSON 正文，因此需要声明它。
model — 选择 ideogram-v3-character。没有它，请求就不知道要路由到哪个模型。
prompt — 场景描述。描述姿势、环境、光照和氛围；将角色身份交给参考图像。
reference_images — 图像 URL 数组。对于单个角色，通常只需一个条目。
aspect_ratio — 输出形状。匹配预期用途（正方形、竖版等）。
num_images — 每个作业生成多少个变体。

成功提交会返回包含作业标识符的 JSON 正文。记下该值——轮询步骤会需要它。响应还可能包含一个状态字段，表明作业正在排队或处理中。如果状态已经是终态，结果可能直接内嵌在响应中；否则，继续轮询。

Python 中的同一请求

下面是 Python 中的完全相同调用。它从环境变量读取密钥，发送请求，并打印作业引用。

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "一位友好的机器人机械师站在阳光充足的工作坊里，手持扳手，四分之三视角",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

关于 Python 版本的说明

timeout=60 可防止脚本在网络不佳时无限挂起。
raise_for_status() 会将非 2xx 响应转换为异常，让你立即注意到身份验证和校验问题。
提取作业 ID — HiAPI 在响应正文中返回作业标识符。根据响应结构不同，它可能位于 id 或 job_id 下；示例检查了两者，但你应该先检查一个真实响应，然后为清晰起见硬编码正确的字段名。

负载刻意与 curl 示例完全相同。在两者之间来回复制 JSON 正文是调试时的良好健全性检查：如果一个能工作而另一个不能，问题出在传输层，而不是模型。

处理用于角色一致性的参考图像

参考图像正是 ideogram-v3-character 与普通文生图模型的区别所在。把它们处理好，就完成了大半工作。

参考图像如何提供

reference_images 字段是一个 URL 数组。每个 URL 都应指向 API 可直接抓取的图像。如果你存储用户上传内容，请从允许未认证 GET 请求的存储桶或 CDN 提供，或生成一个在作业运行期间保持有效的签名 URL。

真正能保持一致性的参考图像技巧

每张参考图只包含一个角色。 合影会让人难以判断要保留哪张脸。
面部清晰、光线良好。 避免重阴影、极端角度和遮挡。
中性或特征性姿势。 正面或四分之三视角最能保留身份特征。
如果你希望保留服装，参考图中的服装应保持一致——模型会复现它看到的内容。
分辨率重要，但不要过度。 尺寸合理且面部清晰的图像，胜过巨大而模糊的图像。

让角色在多次生成中保持可识别

当你为同一角色生成第二个场景时，请复用同一张参考图像，而不是之前生成的输出。链式使用生成图像可能累积细微漂移。如果你需要新的参考图——比如不同服装——先生成一次，检查它，然后将该文件作为后续作业的新参考图复用。

验证一致性

为同一角色生成两到三个不同姿势的变体，并并排比较。如果面部或服装发生漂移，通常原因是参考图较弱或有歧义。在改动提示词之前，先收紧参考图。

异步作业：提交、轮询并获取结果

图像生成需要时间，因此 HiAPI 以异步方式处理。模式始终相同：提交、捕获作业 ID、轮询直到作业达到终态，然后读取输出 URL。

作业生命周期

提交 — 你发送前面示例中的请求。
排队中 — 作业已接受，正在等待容量。
处理中 — 模型正在渲染。
已完成或失败 — 终态；结果（或错误）可用。

在 Python 中轮询

捕获 job_id 后，轮询作业端点：

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

获取结果

作业完成后，响应正文包含输出——通常是图像 URL 数组或单个 URL，外加元数据。请尽快从该 URL 下载图像；某些 URL 有时间限制。如果你需要长期存储，请在作业成功后立即将文件复制到你自己的存储桶。

轮询礼仪

退避。 两秒间隔对短作业没问题；如果你在轮询许多作业，请增加间隔或使用抖动。
限制尝试次数。 max_attempts 防护可防止无限循环，并为代码提供明确的失败路径。
不要以超过需要的速度轮询。 每次轮询都是一个请求；猛击端点不会让渲染更早完成。

常见错误及其诊断方法

出错时，最快的路径通常是先隔离问题出在你的请求、参考图还是作业本身。

身份验证失败

401 表示密钥缺失、格式错误或已撤销。请检查运行请求的 shell 或进程中是否确实设置了环境变量。常见陷阱：在一个终端中设置变量，却在另一个终端中运行脚本。

校验错误

400 几乎总是指向负载。请验证：

model 字段是否恰好为 ideogram-v3-character。
reference_images 是否为数组，而不是字符串。
数组中的每个 URL 是否都可公开访问。
aspect_ratio 是否使用了受支持的值。

如果不确定，请发送最小负载——仅 model、prompt 和 reference_images——然后逐个加回字段。

永不完成的作业

如果轮询超过尝试上限，不要只是盲目重试。检查作业状态响应中是否有消息。常见原因是参考 URL 不可达或队列过载。重新提交一次；如果再次停滞，请简化提示词和参考图。

参考图像被静默忽略

作业成功，但角色不匹配。这通常是参考图问题，而不是代码问题：URL 可能返回错误页面、PDF 或占位图。请自己在浏览器中抓取该 URL，确认它返回的是预期图像且内容类型正确。

速率限制

429 表示你发送请求太快。请使用指数退避；如果你在批量生成，请错开提交，而不是一次性全部发出。

快速检查清单

密钥是否设置到了正确的环境？
参考 URL 是否无需认证即可访问？
负载字段拼写是否正确？
轮询是否设置了上限并进行了退避？
输出是否在其 URL 过期前下载？

按顺序逐项检查该清单，大多数失败都能快速解决。首次端到端运行成功后，请将其保留为已知良好的示例，并将任何新请求与之对比。随着你扩展到许多角色和场景，仅这个习惯就能为你节省时间。

查看全部文章 →