如何通过 hiapi API 使用 flux-2/image-to-image：curl、Python 与可用的请求示例

使用统一的 /v1/tasks 接口进行多参考图编辑——schema、代码与生产实践说明

2026年11月3日

简而言之

这是什么：在 hiapi 上调用 flux-2/image-to-image API 的可用方案——创建任务、轮询状态、下载结果。
端点：使用 POST https://api.hiapi.ai/v1/tasks 并指定 "model": "flux-2/image-to-image"，然后 GET /v1/tasks/<taskId> 直到任务进入终态。
必填输入字段（全部四个）：prompt、image_urls（1–8 个公开 URL——这就是多参考图功能）、aspect_ratio 和 resolution（1K 或 2K）。
schema 是严格的。strength 或 fidelity 等字段并不存在，会被 400 拒绝。保真度由你的参考图、提示词和 resolution 控制——而不是靠单独的旋钮。

你要构建的内容，以及你需要准备什么

目标：向 flux-2 发送一张或多张参考图加一段文本提示词，拿回一张可下载的编辑/重绘图片——用 curl 或 Python，无需 SDK。

前置条件：

一个 hiapi API 密钥——在 hiapi 控制台创建。密钥形如 sk-...，放在 Authorization: Bearer 请求头中。
至少一个可公开访问的图片 URL用作参考图。API 会在服务端抓取 image_urls，因此 localhost 链接或私有存储桶的 URL 不可用——请使用公开存储桶、CDN 或预签名 URL。
curl，或 Python 3.8+ 及 requests（pip install requests）。

请求 schema

flux-2/image-to-image 运行在 hiapi 的统一任务接口上。input 对象恰好接受以下字段：

字段	类型	必填	说明
`prompt`	string	是	要修改或生成的内容。至少 3 个字符。
`image_urls`	string[]	是	1–8 个公开图片 URL。多于一张 = 多参考图：flux-2 会在所有参考图之间融合身份、产品或风格线索。
`aspect_ratio`	string	是	`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3` 或 `auto`（跟随参考图）之一。
`resolution`	string	是	`1K` 或 `2K`。

其他任何字段都会被拒绝。例如，发送 strength 或 fidelity 字段会返回：

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

这一点值得牢记：flux-2 的图生图模式没有去噪强度旋钮。输出对参考图的忠实程度（“高保真”编辑 vs. 松散重绘）取决于你如何编写提示词——例如 “保持产品及其标签和比例与参考图完全一致；只替换背景”——再加上对细节要求高的工作使用 resolution: "2K"。

最小可用示例：curl

第 1 步——创建任务：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

创建成功会在 data.taskId 中返回任务 ID。

第 2 步——轮询直到完成：

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

只要 data.status 不是终态，就每隔几秒继续轮询。当 "status": "success" 时，图片 URL 位于 data.output[0].url。

第 3 步——立即下载结果：

curl -s -o result.jpg "OUTPUT_URL"

输出 URL 带有 expireAt 时间戳——它们是临时的。任务成功后应立即下载字节（或复制到你自己的存储）；不要在生产环境中直接热链任务输出。

最小可用示例：Python

一个完整脚本——创建、轮询、下载——仅使用 requests：

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # 临时 URL——请立即保存
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

注意这里用了两张图的 image_urls——这就是多参考图的实际用法。最多接受 8 张参考图；模型会在它们之间进行组合（人物 + 服装、产品 + 背景风格、角色 + 姿势参考，等等）。

生产实践说明

用回调代替轮询。对于脚本之外的任何场景，在创建任务时注册回调，让 hiapi 将终态结果推送给你的服务：

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

使用 "when": "final" 时，任务进入终态你只会收到一次 POST。经验法则：轮询适合 CLI、批处理和任何短生命周期场景；回调更适合面向用户的应用，因为每张图都让一个 worker 持有轮询循环无法扩展。如果你无法暴露公开的回调端点，那就轮询——只是要把间隔退避到 5 秒以上。

让重试安全。把任务创建当作它本来的副作用来处理：在根据结果行动之前，将返回的 taskId 存到你自己的作业记录中；重试时，重新检查已存储任务的状态，而不是盲目创建新任务（每次成功创建都会单独计费）。如果你的作业运行器可能触发两次，请先按你自己的作业 ID 去重。

处理你实际会遇到的错误：

401 permission_denied——密钥错误，或密钥无权使用该模型。响应体如下：
```
{"error": {"code": "permission_denied",
           "message": "This API key cannot use the selected model. ...",
           "type": "hiapi_error"}}
```
在控制台检查密钥；我们的无效 API 密钥检查清单涵盖了常见原因。
400 INVALID_REQUEST——schema 违规。message 会一次性列出所有违规字段（缺少必填字段、错误的枚举值、未知的额外字段），因此请完整阅读，而不是每次重试只修一个字段。
任务 status: "fail"——任务已被接受但生成失败；错误位于 data.error 中。请在轮询/回调路径中处理，而不是在创建时处理。
输出 URL 过期——如果成功几分钟后下载返回 4xx，说明你等太久了。重新检查 expireAt，并且始终立即下载。

常见问题

我可以向 flux-2 图生图传递多少张参考图？ 1 到 8 张，作为公开 URL 放在 image_urls 中。超过 8 张会校验失败（maxItems: got N, want 8）。

有 strength 或 fidelity 参数吗？ 没有。输入 schema 只接受 prompt、image_urls、aspect_ratio 和 resolution；未知字段会以 400 拒绝。通过提示词措辞控制保真度（明确说明哪些必须保持不变），并在细节重要时使用 2K。

支持哪些分辨率和宽高比？ resolution 为 1K 或 2K。aspect_ratio 为 1:1、4:3、3:4、16:9、9:16、3:2、2:3 或 auto 之一——auto 跟随你的参考图，这通常是编辑时想要的。