跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

Ideogram 4.5 Edit 图片编辑 API

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

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 ideogram-v4.5/image-to-image
类型 图像编辑（图生图）
接口 POST /v1/tasks
价格 见 HiAPI 定价

Ideogram 4.5 图片编辑：以一张主源图片和自然语言指令完成文字、场景与风格编辑，可选参考图、遮罩和编辑精度。

生产建议

生产环境建议
  • 生产环境可以在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时通知你的服务。
  • GET /v1/tasks/:id 适合本地调试、低频任务或回调失败后的补偿查询。
  • success 和 fail 都是终态，请按 taskId 做幂等处理。

适用场景

保留主体的局部编辑

用 prompt 写清修改项和必须保留的主体、文字、构图与光线。

promptimage_url
多参考图合成

可增加最多 4 张参考图，并在 prompt 中说明每张图的作用。

reference_image_urlsprompt
遮罩与精度控制

使用 mask_url 指定可编辑区域，并按需要选择 regular 或 high。

mask_urledit_precision

请求参数

model string 必填

固定填 ideogram-v4.5/image-to-image。

示例 ideogram-v4.5/image-to-image
input object 必填

业务参数对象；Ideogram 4.5 图片编辑的配置放在这里。

prompt string 必填

描述要修改的内容与必须保留的内容；长度为 1–10000 个字符。

image_url string 必填

主源图片的公开 URL，编辑将在这张图片上进行。

reference_image_urls string[] 可选

可选参考图片 URL 数组，最多 4 张；传入 mask_url 时最多 3 张。

mask_url string 可选

可选遮罩图片 URL；黑色区域允许编辑，白色区域保留。遮罩尺寸应与主源图片匹配。

edit_precision enum 可选

编辑精度。high 会更强调未修改像素的保留，此时 quality 不支持 very_low。

默认 regular 可选值: regularhigh
quality enum 可选

输出质量档位。edit_precision=regular 支持全部四档；edit_precision=high 支持 low、medium、high。

默认 medium 可选值: very_lowlowmediumhigh
image_size enum 可选

输出尺寸预设；编辑省略时使用 auto。

默认 auto 可选值: autosquaresquare_hdportrait_4_3landscape_4_3portrait_16_9landscape_16_9
num_images integer 可选

一次生成的图片数量，范围为 1–8。

默认 1
seed integer 可选

可选随机种子；使用相同输入和种子有助于复现结果。

callback object 可选

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

url string 必填

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

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机；当前使用 final。

默认 final 可选值: final

用例示例

提示词编辑：海报改冬季版

regular + very_low，只换配色和背景，文字与版式保留。

请求体
{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Turn this festival poster into a winter edition: icy blue and silver palette, snowy mountains replacing the sunset, keep all text and layout the same",
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385709978-062553a94718311d-t2.png",
    "edit_precision": "regular",
    "quality": "very_low",
    "image_size": "auto",
    "num_images": 1
  }
}
Precise Edit 改 Logo 文字

edit_precision=high，只改文字，其余像素还原；尺寸必须为 auto。

请求体
{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385709528-9ea916b16cbb5255-t1.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}
参考图改风格

1 张参考图提供配色和包装风格。

请求体
{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Restyle this coffee logo using the jade green and gold color scheme and premium packaging style of the reference image, keep the text \"Ember & Oak\" readable",
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385709528-9ea916b16cbb5255-t1.png",
    "reference_image_urls": [
      "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385710363-67646b28c0cefc08-t3.png"
    ],
    "edit_precision": "regular",
    "quality": "very_low",
    "image_size": "auto",
    "num_images": 1
  }
}
蒙版局部重绘

黑色区域重绘、白色区域保留；带蒙版时尺寸必须为 auto。

请求体
{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "The woman wears an emerald green wool trench coat instead of the red coat",
    "image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385710761-72fd4b52d2d96338-t4.png",
    "mask_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385384980-4d8619ba40031f9b-e3-mask.png",
    "edit_precision": "regular",
    "quality": "very_low",
    "image_size": "auto",
    "num_images": 1
  }
}

获取结果

  1. 提交成功后立即返回 taskId。
  2. 生产环境优先等待 callback.url 的终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后从 output[].url 下载图片。
  4. status=fail 时根据错误信息修正请求。

常见问题

图片编辑需要哪些输入？

必须提供 prompt 和 image_url；可按需增加参考图、遮罩、编辑精度和质量档位。

regular 和 high 编辑精度有什么区别？

regular 支持四档 quality；high 更强调保留未修改像素，此时不能使用 very_low。

遮罩如何使用？

遮罩黑色区域允许编辑，白色区域保留；遮罩尺寸应与主源图片匹配。

参考图最多几张？

通常最多 4 张；传入 mask_url 时最多 3 张参考图。

下一步