Ideogram 3.0 Character Edit
POST Base URL:
https://api.hiapi.ai /v1/tasks 图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。
模型概览
| 模型名称 | ideogram-v3-character/edit |
|---|---|
| 类型 | 局部编辑（角色一致性） |
| 接口 | POST /v1/tasks |
| 价格 | 见 HiAPI 定价 |
用蒙版指定区域，把参考角色局部重绘进原图；三档按张计价。
生产建议
生产环境建议
- 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务。
- 图片 URL 必须是公网可访问的 http/https 地址。
请求参数
model string 必填 固定填 ideogram-v3-character/edit。
input object 必填 业务参数对象。每次固定输出 1 张图。
prompt string 必填 画面/改动描述，1–5000 字符。
image_url string 必填 要编辑的原图公网 URL，需与蒙版宽高比一致；输出尺寸跟随原图。
mask_url string 必填 蒙版公网 URL：黑色区域会被重绘、白色保留，需与原图宽高比一致。
reference_image_urls string[] 必填 角色参考图，恰好 1 张（JPEG/PNG/WebP，≤10MB）。
rendering_speed enum 可选 渲染速度档，三档按张分别计价。
style enum 可选 风格类型。
expand_prompt boolean 可选 是否用 MagicPrompt 扩写提示词。
seed integer 可选 随机种子，0–2147483647。
callback object 可选 可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。
url string 必填 传入 callback 时必填；接收任务终态通知的 HTTPS 地址。
when enum 可选 回调触发时机；当前建议固定为 final。
用例示例
Ideogram 3.0 Character Edit API
用蒙版指定区域，把参考角色局部重绘进原图；三档按张计价。
请求体
{
"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（不等待生成完成）。
- 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
- status=success 后，从返回的 output[].url 下载生成的图片。
- 如果 status=fail，按返回的错误信息修正请求。
常见问题
三档 rendering_speed 怎么选？
TURBO 最快最省，适合迭代；BALANCED 为默认档；QUALITY 细节最好，适合定稿。三档按张分别计价。 查看价格
可以传多张角色参考图吗？
不可以。reference_image_urls 必须恰好 1 张；多传会直接返回 400。
可以指定输出比例吗？
不能单独指定。输出宽高比跟随角色参考图（生成）或原图（编辑）。需要横图时，请上传横版角色参考图。
支持 Remix 吗？
暂不支持 Remix，当前只开放角色生成与蒙版局部编辑。
一次能出几张图？
每次固定 1 张，按张计费。需要多张请并发提交多个任务。
怎么拿到生成的图片？
提交后立即返回 taskId，任务进入终态后从 output[].url 下载 WebP 图片。生产环境建议在请求体顶层传 callback.url 收终态通知。