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

FLUX.2 Image to Image API

POST /v1/tasks

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

模型概览

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

FLUX.2 专业档图像编辑:最多 8 张参考图的多图合成、背景替换、风格与材质改造,主体一致性强,1K/2K 按张计费。

生产建议

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

适用场景

多参考图合成

一次最多 8 张参考图,按指令把主体、Logo、材质合进同一画面,序号引用(图 1/图 2)控制各图角色。

image_urlsprompt
背景替换与场景迁移

主体不动换环境,光影与反射自动匹配新场景,产品图/人像换景一句话完成。

prompt
风格与材质改造

照片转水彩/插画/3D,或把物体改成黄金、玻璃等新材质,保持构图一致。

prompt
按张计费分档清晰

1K/2K 两档按张计费,价格与参考图数量无关,批量编辑成本可控。

resolution

请求参数

model string 必填

固定填 flux-2/image-to-image。

示例 flux-2/image-to-image
input object 必填

业务参数对象；FLUX.2 Image to Image 的模型专属配置都放在这里。

prompt string 必填

编辑指令,3-5000 字符。可按序号引用参考图,如"图 1 的罐子装上图 2 的胶囊"。

image_urls string[] 必填

参考图 URL 数组,1-8 张;jpeg/png/webp,不支持 svg,单张最大 10MB。

aspect_ratio enum 必填

输出图片比例;auto 表示跟随第一张参考图的比例。

默认 1:1 可选值: 1:14:33:416:99:163:22:3auto
resolution enum 必填

输出图片分辨率。

默认 1K 可选值: 1K2K
callback object 可选

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

url string 必填

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

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

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

默认 final 可选值: final

用例示例

水彩风格转换

单参考图 + auto 比例实测:照片转柔和水彩插画。

请求体
{
  "model": "flux-2/image-to-image",
  "input": {
    "prompt": "Turn this scene into a delicate watercolor illustration with soft pastel tones and visible paper texture, keep the original composition",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/07/7ec4868888f6156f.png"
    ],
    "aspect_ratio": "auto",
    "resolution": "1K"
  }
}
双参考图合成(2K)

两张参考图合成实测:图 1 主体放进图 2 场景,光影统一。

请求体
{
  "model": "flux-2/image-to-image",
  "input": {
    "prompt": "Place the glowing translucent grand piano from image 1 onto the wooden desk scene from image 2, keep the moody neon studio lighting and cinematic color grade, seamless composite",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/07/564b6163a46a3dc4.png",
      "https://static.hiapi.ai/gallery/2026/07/2494abb7645b98f8.png"
    ],
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }
}
材质改造(24K 黄金)

材质编辑实测:唱机改造成雕花黄金,场景与打光保持。

请求体
{
  "model": "flux-2/image-to-image",
  "input": {
    "prompt": "Transform the record player into polished 24k gold with engraved art-deco patterns, keep the studio scene and lighting, photorealistic product shot",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/07/2494abb7645b98f8.png"
    ],
    "aspect_ratio": "auto",
    "resolution": "1K"
  }
}

获取结果

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

常见问题

和 flux-2/text-to-image 什么关系?

同一 FLUX.2 专业档家族:文生图走 flux-2/text-to-image,基于参考图的编辑/合成走本端点。

最多几张参考图?怎么引用?

1-8 张(jpeg/png/webp,单张 ≤10MB)。在 prompt 里按序号引用,如"图 1 的主体放进图 2 的场景"。

参考图数量影响价格吗?

不影响。按输出张数计费,按 1K/2K 分辨率分档,与参考图数量无关。

aspect_ratio 的 auto 是什么?

输出比例自动跟随第一张参考图的比例,适合"改内容不改画幅"的编辑。

下一步