Ideogram V4 API

POST /v1/tasks

所有模型都通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称	ideogram-v4
类型	图像生成（文生图）
接口	POST /v1/tasks
价格	见 HiAPI 定价

Ideogram V4:排版专家——Logo、海报、招牌的画面文字准确率标杆,TURBO/BALANCED/QUALITY 三档按张计价。

生产建议

生产环境建议

生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

Logo 与品牌字标

定制字标、字母组合、图形融合(如咖啡豆融进 & 符号)一次成型,矢量级干净边缘。

promptrendering_speed

海报与排版设计

标题+副标题+多行文字的完整排版,拼写准确率行业标杆,英文效果最佳。

prompt

招牌与灯箱

霓虹灯管字、立体金属字、灯箱字等带材质的文字效果高度可控。

prompt

三档速度按需选

TURBO 迭代构图、QUALITY 定稿输出,约 3 倍价差,预算灵活。

rendering_speed

请求参数

POST https://api.hiapi.ai/v1/tasks

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 API Key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v4",
  "input": {
    "prompt": "An art deco cinema marquee at night: the words GRAND PALACE THEATRE in glowing gold channel letters, NOW SHOWING on a smaller board below, brass and burgundy facade, warm bulbs, all lettering accurate and crisp, symmetrical composition",
    "aspect_ratio": "16:9",
    "rendering_speed": "QUALITY"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "ideogram-v4",
  "input": {
    "prompt": "An art deco cinema marquee at night: the words GRAND PALACE THEATRE in glowing gold channel letters, NOW SHOWING on a smaller board below, brass and burgundy facade, warm bulbs, all lettering accurate and crisp, symmetrical composition",
    "aspect_ratio": "16:9",
    "rendering_speed": "QUALITY"
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 API Key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "ideogram-v4",
  "input": {
    "prompt": "An art deco cinema marquee at night: the words GRAND PALACE THEATRE in glowing gold channel letters, NOW SHOWING on a smaller board below, brass and burgundy facade, warm bulbs, all lettering accurate and crisp, symmetrical composition",
    "aspect_ratio": "16:9",
    "rendering_speed": "QUALITY"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

固定填 ideogram-v4。

示例 ideogram-v4

input object 必填

业务参数对象；Ideogram V4 的模型专属配置都放在这里。

prompt string 必填

画面描述;要渲染的文字逐字写进提示词——准确排版是这款模型的看家本领。

aspect_ratio enum 可选

输出画幅(约 1MP 预设尺寸)。

默认 1:1 可选值: 1:116:94:39:163:4

rendering_speed enum 必填

渲染速度档:TURBO 最快最省 / QUALITY 细节最好;三档价格不同。

默认 BALANCED 可选值: TURBOBALANCEDQUALITY

output_format enum 可选

输出图片格式。

默认 jpeg 可选值: jpegpng

seed integer 可选

随机种子,固定后可复现。

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

影院灯箱门头(QUALITY)

立体发光字 + 对称构图,定稿档实测。

请求体

{
  "model": "ideogram-v4",
  "input": {
    "prompt": "An art deco cinema marquee at night: the words GRAND PALACE THEATRE in glowing gold channel letters, NOW SHOWING on a smaller board below, brass and burgundy facade, warm bulbs, all lettering accurate and crisp, symmetrical composition",
    "aspect_ratio": "16:9",
    "rendering_speed": "QUALITY"
  }
}

咖啡品牌字标(TURBO)

最低成本出 Logo 初稿。

请求体

{
  "model": "ideogram-v4",
  "input": {
    "prompt": "A minimalist coffee shop logo design: the words BREW & CO in an elegant custom serif wordmark, a subtle coffee bean integrated into the ampersand, warm espresso brown on cream background, centered composition, premium brand identity, vector-clean edges",
    "aspect_ratio": "1:1",
    "rendering_speed": "TURBO"
  }
}

京都旅行海报(TURBO)

手写复古标题 + 扁平插画。

请求体

{
  "model": "ideogram-v4",
  "input": {
    "prompt": "A vintage travel poster of Kyoto: the word KYOTO in large hand-lettered retro type at the top, subtitle JAPAN below, a pagoda among maple trees in flat mid-century illustration style, autumn palette, all lettering accurate",
    "aspect_ratio": "3:4",
    "rendering_speed": "TURBO"
  }
}

获取结果

提交成功后立即返回 taskId（不等待生成完成）。
生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
status=success 后，从返回的 output[].url 下载生成的图片。
如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

三档 rendering_speed 差在哪?

TURBO 最快最便宜,适合迭代构图;BALANCED 均衡;QUALITY 细节最好、单价约为 TURBO 的 3 倍,适合定稿。三档按张分别计价,实时价格见价格页。查看价格

中文文字渲染效果如何?

Ideogram 的强项是英文排版,英文拼写准确率行业标杆;中文可以渲染但准确率不如英文,中文文字为主的画面建议用 seedream-5.0-lite 或 qwen-image-2.0-pro。

提示词怎么写文字最稳?

把要渲染的文字用大写或引号明确框出(如 the words BREW & CO),并注明 all lettering accurate;一张图的文字总量越少越稳。

怎么拿到生成的图片?

提交后立即返回 taskId,任务进入终态后从 output[].url 下载图片。生产环境建议在请求体顶层传 callback.url 收终态通知,减少无效轮询。