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

GPT Image 2 Image-to-Image (Multi-ratio 4K) API

POST /v1/tasks

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

模型概览

模型名称 gpt-image-2/image-to-image@ext
类型 图像生成（图生图）
接口 POST /v1/tasks
价格 见 HiAPI 定价

GPT Image 2 图生图高分辨率多比例线：最多 16 张参考图融合编辑，16 种画幅比例 × 1K/2K/4K × 低/中/高三档质量自由组合，改图、风格迁移、多图合成都能精确控制输出画幅与质感。

生产建议

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

适用场景

改图与风格迁移

上传原图 + 一句编辑指令即可换风格、改光线、替换元素；aspect_ratio 留 auto 输出跟随原图比例，改图不变形。

promptimage_urls
多图融合合成

最多 16 张参考图一次融合：产品图 + 场景图合成宣传物料、多角色合成海报，价格与图张数无关。

image_urls
固定画幅的高分辨率重制

把已有素材重制成 5:4、4:5、2:1 等指定比例的 2K/4K 输出，适合把社媒图翻制成印刷物料。

aspect_ratioresolution
分档控制成本

批量改图走 low 档，客户交付切 medium/high；质量 × 分辨率 9 档独立计价，与参考图张数无关。

qualityresolution

请求参数

model string 必填

固定填 gpt-image-2/image-to-image@ext。

示例 gpt-image-2/image-to-image@ext
input object 必填

业务参数对象；GPT Image 2 Image-to-Image (Multi-ratio 4K) 的模型专属配置都放在这里。

prompt string 必填

图像编辑指令，最长 20000 字符。

image_urls string[] 必填

参考图数组，1-16 张；支持公网 URL 和 data URI 混用。单图最大 20 MB，总计不超过 256 MB。

aspect_ratio enum 可选

输出画幅比例；默认 auto 跟随输入图比例，显式指定则强制输出该比例。

默认 auto 可选值: auto1:13:22:34:33:45:44:516:99:16 +6
resolution enum 必填

分辨率档位：1K 约 1024px、2K 约 2048px、4K 最高 3840×2160；实际像素随比例变化。

默认 1K 可选值: 1K2K4K
quality enum 必填

质量档位，影响价格：low 干净锐利适合走量，medium 细节明显提升，high 电影级质感。

默认 low 可选值: lowmediumhigh
callback object 可选

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

url string 必填

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

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

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

默认 final 可选值: final

用例示例

改成夜景

单图编辑：保留主体，把场景改成挂灯笼的夜景（本文档的示例输入/输出即来自这条真实请求）。

请求体
{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "make it a night scene with lanterns",
    "image_urls": [
      "https://static.hiapi.ai/model-assets/gpt-image-2-ext/2026/07/02/1782989773168-fd7b2316f1a92a9f-i2i-input-apple.webp"
    ],
    "aspect_ratio": "5:4",
    "resolution": "2K",
    "quality": "medium"
  }
}
双图融合海报

两张参考图融合成一张 4:5 竖版海报，适合社媒宣传位。

请求体
{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "fuse these two images into a cinematic poster, dramatic lighting",
    "image_urls": [
      "https://example.com/photo-a.jpg",
      "https://example.com/photo-b.jpg"
    ],
    "aspect_ratio": "4:5",
    "resolution": "2K",
    "quality": "medium"
  }
}

获取结果

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

常见问题

和标准版 gpt-image-2/image-to-image 有什么区别？

本线支持全部 16 个比例在 1K/2K/4K 下输出（标准线的 2K/4K 不支持 5:4、4:5 等比例）、最多 16 张参考图（标准线 5 张），并提供低/中/高三档质量选择。

价格和参考图张数有关吗？

无关。按质量 × 分辨率分档计费（共 9 档），传 1 张图和 16 张图价格相同。实时价格以定价页为准。 查看实时价格

aspect_ratio 填 auto 和显式指定有什么区别？

auto（默认）时输出跟随输入图的比例，适合原位改图；显式指定比例则强制输出该画幅，适合把素材重制成固定版式。

参考图有什么格式和大小限制？

支持公网 URL 和 base64 data URI 混用，1-16 张；单图最大 20 MB，一次请求总计不超过 256 MB。

下一步