教程
如何通过 hiapi API 使用 ideogram-v4：curl、Python 以及一个可用的请求
Ideogram 模型的名声建立在一件大多数图像模型至今仍搞不定的事情上：排版。海报上的标题拼写正确，标志上的字母干净利落，招牌文字不会糊成一团乱码。ideogram-v4 和其他所有图像、视频模型一样，通过同一个统一任务 API 在 hiapi 上可用，本指南会完整走一遍这个请求：可直接复制粘贴的 curl 版本、完整的 Python 脚本、schema 实际校验的参数（它们和 Ideogram 原生 API 暴露的并不相同），以及你在实践中会遇到的错误。
你要构建什么，需要准备什么
目标：向 POST /v1/tasks 发送一个文本提示词，等待任务完成，然后下载一张文字按照你的要求渲染出来的图像。
你只需要一样东西：一个 hiapi API 密钥 —— 在控制台中创建一个。它在每个请求中作为 Bearer token 使用。没有免费的未认证层级；下面所有调用都假定使用 Authorization: Bearer sk-...。
和 hiapi 上的所有模型一样，ideogram-v4 是异步的：你创建一个任务，立刻拿到一个 taskId，然后要么轮询结果，要么接收回调。不存在同步的“在一个 HTTP 连接上等 40 秒”模式——而且对于图像生成来说，你本来也不会想要这种模式。
最小请求：curl
创建任务：
curl -X POST https://api.hiapi.ai/v1/tasks \
-H "Authorization: Bearer $HIAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4",
"input": {
"prompt": "一张复古装饰艺术风格的爵士音乐节海报。主标题文字 \"MIDNIGHT & BRASS\" 使用粗体金色字体，背景为深海军蓝，副标题 \"Live at the Riverside, Fridays\" 在其下方使用纤细的无衬线字体。",
"rendering_speed": "BALANCED",
"aspect_ratio": "3:4"
}
}'
响应会立即返回，任务 id 位于 data.taskId（形如 tk-hiapi-...）。轮询它：
curl https://api.hiapi.ai/v1/tasks/tk-hiapi-XXXXXXXX \
-H "Authorization: Bearer $HIAPI_KEY"
在图像生成期间，data.status 会依次经过 queued 和 handling。到达终态时会变成 success 或 fail。成功时，图像 URL 位于 data.output[0].url：
{
"code": 200,
"data": {
"taskId": "tk-hiapi-XXXXXXXX",
"status": "success",
"output": [
{ "url": "https://.../result.png?...expireAt=..." }
]
}
}
这个 URL 有一点要注意：它是签名的，而且会过期（expireAt）。任务成功后立刻下载字节内容，并保存到你自己的存储中。永远不要把热链接存进数据库。
ideogram-v4 实际接受的参数
这是值得精确对待的部分。如果你读过 Ideogram 自己的文档，就会知道其原生 API 暴露了风格预设、魔法提示词开关、负面提示词和批量数量。hiapi 的 ideogram-v4 任务 schema 有意做得更小，校验器会拒绝 schema 之外的任何内容。以下是经过实时 API 确认的完整范围：
| 字段 | 必填 | 类型 / 取值 |
|---|---|---|
prompt |
是 | string |
rendering_speed |
是 | "TURBO"、"BALANCED"、"QUALITY" |
aspect_ratio |
否 | "1:1"、"16:9"、"4:3"、"9:16"、"3:4" |
seed |
否 | 整数 |
两个必填字段都会强制校验。发送空 input 会得到：
invalid input: prompt: missing required field "prompt";
rendering_speed: missing required field "rendering_speed"
枚举值拼错时，错误会告诉你合法取值：
invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
而 Ideogram 原生接口中不在上表里的任何内容，都会被当作未知属性拒绝——style_type、magic_prompt、negative_prompt、num_images、size 以及图像输入都会返回 400，例如：
invalid input: <root>: additional properties 'style_type' not allowed
实际影响：
- 排版控制完全依靠提示词。 把你想渲染的确切文本用双引号放进提示词里，并描述字体（“粗体装饰艺术字体”、“纤细几何无衬线体”、“手绘招牌字体”）。这就是获得 Ideogram 赖以成名的海报/标志/招牌效果的方式——没有单独的风格参数可以依赖。
- 每个任务一张图像。 没有
n或num_images。如果你想要四个候选，就提交四个任务，并分别轮询每个taskId。 seed是你的可复现性旋钮。 相同的提示词 + 相同的 seed 会给你一个稳定的起点，便于迭代措辞。- 仅支持文生图。 该模型 schema 不接受参考图像。如果你的工作流需要图生图，请选择支持该功能的模型——参见如何用一个 API 密钥调用多个图像模型，在不改动集成代码的情况下切换模型。
关于 rendering_speed：TURBO 是快速层级，适合在你迭代提示词措辞时打草稿；QUALITY 是缓慢、精细的层级，适合最终渲染；BALANCED 是合理的默认值。定价按每张图像的使用量计费——当前价格请查看定价页面。
完整的 Python 脚本
同样的流程——创建、轮询、下载——带有超时和终态处理。唯一依赖是 requests（pip install requests）。
import os
import time
import requests
API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
"Content-Type": "application/json",
}
def create_task(prompt: str, rendering_speed: str = "BALANCED",
aspect_ratio: str = "1:1", seed: int | None = None) -> str:
input_obj = {
"prompt": prompt,
"rendering_speed": rendering_speed,
"aspect_ratio": aspect_ratio,
}
if seed is not None:
input_obj["seed"] = seed
resp = requests.post(API_BASE, headers=HEADERS,
json={"model": "ideogram-v4", "input": input_obj},
timeout=60)
data = resp.json()
task_id = (data.get("data") or {}).get("taskId")
if not task_id:
raise RuntimeError(f"create failed: HTTP {resp.status_code} {data}")
return task_id
def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
task = resp.json().get("data") or {}
status = task.get("status")
if status == "success":
return task
if status == "fail":
err = task.get("error") or {}
raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} not done after {timeout_s}s")
if __name__ == "__main__":
task_id = create_task(
prompt=('为一家名为 "Driftwood" 的咖啡品牌设计极简标志，'
'单词 Driftwood 使用温暖的衬线字体字标，单色，'
'奶油色背景'),
rendering_speed="QUALITY",
aspect_ratio="1:1",
seed=42,
)
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]
png = requests.get(url, timeout=120).content # 签名 URL 会过期 - 立即下载
with open("driftwood-logo.png", "wb") as f:
f.write(png)
print("saved driftwood-logo.png,", len(png), "bytes")
生产环境注意事项：回调、幂等性和错误
轮询 vs. 回调。 对于一次生成一张图像的交互式工具，每隔几秒轮询更简单，而且完全够用。对于批处理或服务端工作负载，在创建请求中添加回调，让 hiapi 把终态结果 POST 给你：
{
"model": "ideogram-v4",
"input": { "prompt": "...", "rendering_speed": "BALANCED" },
"callback": { "url": "https://your.domain.example/hiapi/hook", "when": "final" }
}
有两个约束，都在创建时强制执行：URL 必须是 https:// 且可从公网访问，when 只接受 "final"——如果你尝试其他值，API 会直接返回 invalid callback.when: only 'final' is supported。让你的处理程序对 taskId 幂等，快速返回 2xx，并为回调始终未到达的任务保留轮询兜底。如果回调没有到达，先按照为什么你的 hiapi 任务回调没有触发排查，再怪罪队列。
幂等性。 创建任务不是幂等的——每次成功的 POST /v1/tasks 都是一个新任务和一次新计费。收到 taskId 后立刻把它和你自己的任务 id 关联存储，之后任何重试都轮询已存储的 taskId，而不要重新提交。
你实际会看到的错误。
401伴随"code": "permission_denied"——密钥无效或无法使用该模型。消息会明确说明：“This API key cannot use the selected model. Please check permissions or use another key.” 在控制台中修复，不要重试。400伴随"error_code": "INVALID_REQUEST"——校验失败。message会指出具体字段和合法取值；阅读它，修正请求体。用相同的请求体重试会永远失败。GET /v1/tasks/{id}上的404"task not found"——任务 id 错误，或任务是用另一个密钥创建的。- 已被接受的任务出现
fail状态——检查轮询响应中的data.error.code/data.error.message。这些可以安全地作为新任务重试。
相关阅读
- ideogram-v4 模型页面——能力与当前定价层级
- 为什么你的 hiapi 任务回调没有触发——回调调试清单
- 如何用一个 API 密钥调用多个图像模型——同一个任务 API，不同的
model字符串 - 最便宜的图像生成 API——如何比较各模型的真实单图成本
- API 文档——完整的
POST /v1/tasks/GET /v1/tasks/{id}参考
常见问题
hiapi 上的 ideogram-v4 支持图生图或参考图像吗？
不支持。该模型的任务 schema 只接受 prompt、rendering_speed、aspect_ratio 和 seed——任何图像输入字段都会以 400 被拒绝。如果你需要编辑或重绘现有图像，请使用支持图生图的模型（例如 gpt-image-2 系列）。
我应该用哪个 rendering_speed？
在你优化提示词和文本确切措辞时，用 TURBO 迭代，然后用 QUALITY 和相同的 seed 重新渲染最终胜出的版本。如果你只渲染一次，BALANCED 是不错的默认值。
如何让 ideogram-v4 渲染出确切的文字？
把字面文本用双引号放进提示词，并在周围描述排版：主标题文字 "SUMMER SALE"，使用粗重压缩无衬线体。较短的字符串比完整句子渲染更可靠；如果长行渲染出来是乱的，就把它拆成主标题和副标题。
可以在一个请求中生成多张图像吗？
不可以——一个任务生成一张图像。改为并行提交多个任务；每个任务都有自己的 taskId，并独立排队。
为什么我的密钥对其他模型有效，却得到 401 permission_denied？
模型访问权限是按密钥配置的。在控制台中检查该密钥的模型权限，或创建一个有权访问 ideogram-v4 的新密钥。
输出 URL 的有效期是多久？
它是一个带 expireAt 时间戳的签名 URL。把它当作分钟级而非天级：任务一到达 success 就下载图像，并自己保存文件。
有哪些可用的宽高比？
正好五种：1:1、16:9、4:3、9:16 和 3:4。没有自由格式的 size 参数——带 size 的请求会作为未知属性被拒绝。
