如何通过 hiapi API 使用 seedream-5.0-lite 图生图

这篇教程将向你展示如何通过 hiapi 统一任务 API 调用 seedream-5.0-lite 的图生图模式：精确的请求结构、可直接运行的 curl 命令、可以放进后端的 Python 脚本，以及这个模型强制执行而其他模型不会的校验陷阱。

读完本文，你将拥有一个脚本：它接收一个或多个参考图 URL 以及一条编辑提示词，返回一个可立即下载的生成图片 URL。

你需要准备什么

• 一个 hiapi 账号和一个 API key。可以在 hiapi 控制台获取。
• 一张或多张托管在公共 HTTPS URL 上的参考图。该模型单次请求最多接受 14 张参考图，这正是它对多参考图工作流有用的原因——把一张图里的主体与另一张图的风格或场景融合。
• 一段描述编辑或变换的文本提示词（最少 3 个字符——没错，API 会校验这一点）。

所有请求都发往统一任务端点，密钥放在 Authorization 请求头中：

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

请求结构（以及该模型的要求）

模型 id 是 seedream-5.0-lite/image-to-image——直接原样传入，与 /v1/models 中列出的完全一致。它的 input schema 很严格，四个字段全部必填：

字段	类型	说明
prompt	string	编辑指令。最小长度 3。
image_urls	string[]	1–14 张参考图 URL。
aspect_ratio	string	取值为 1:1、4:3、3:4、16:9、9:16、2:3、3:2、21:9 之一。
resolution	string	只能是 2K 或 4K。该模型没有 1K 档位。

从平台上其他模型迁移过来的人常会踩两个坑：

1. resolution 只接受 2K 或 4K。如果你的共享任务提交代码默认填 "1K"（这在很多其他图像模型上可用），该模型会以 400 拒绝。
2. 多余字段会被拒绝，而不是被忽略。发送 size、n 或 schema 之外的任何内容都会返回 400 INVALID_REQUEST，并附带 additional properties '<field>' not allowed。任务 API 按模型校验 input——不要盲目复用另一个模型的 payload。

最小可运行示例：curl

创建任务：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Replace the background with a sunlit Tokyo street at golden hour, keep the subject unchanged",
      "image_urls": ["https://your-cdn.example.com/subject.png"],
      "aspect_ratio": "3:2",
      "resolution": "2K"
    }
  }'

成功提交后会在 data 中返回一个任务 id：

{"code": 200, "data": {"taskId": "task_abc123..."}}

轮询结果：

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk-<your-key>"

运行期间，data.status 为 pending/processing。完成后会变为 "success"，图片出现在 data.output 中：

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

输出 URL 是短时有效的（注意 expireAt）。请立即下载字节并自行存储——不要热链或持久化原始 URL。

多参考图：传入多张图片

要融合多张参考图——比如一张产品图加一张风格参考图——只需向 image_urls 添加更多 URL，并在提示词中说明每张图贡献什么：

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": {
    "prompt": "Place the product from the first image into the scene from the second image, matching its lighting and color grade",
    "image_urls": [
      "https://your-cdn.example.com/product.png",
      "https://your-cdn.example.com/scene-reference.jpg"
    ],
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}

硬性上限是 14 个 URL；第 15 个会返回 400 INVALID_REQUEST: image_urls: maxItems: got 15, want 14。实践中，2–4 张精心挑选的参考图，配合明确为每张图分配角色的提示词（“保留图 1 中的主体，采用图 2 的配色”），比一堆松散相关的图片能带来可控得多的编辑效果。

对单张图片做精确、有针对性的编辑——换背景、改服装、移除物体——使用一个参考 URL，并同时说明要改什么和要保留什么（“保持面部和姿态不变”）。Seedream 模型能很好地遵循保留指令，明确说明正是区分精准编辑与完全重新诠释的关键。

生产可用的 Python：提交、轮询、下载

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Create the task
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,  # this model: "2K" or "4K" only
        },
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. Poll until terminal state
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Download immediately — the URL expires
            img = requests.get(outputs[0]["url"], timeout=120)
            img.raise_for_status()
            return img.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} still running after 600s")


if __name__ == "__main__":
    png = edit_image(
        "Replace the background with a minimalist studio backdrop, keep the subject unchanged",
        ["https://your-cdn.example.com/subject.png"],
        aspect_ratio="3:2",
    )
    with open("edited.png", "wb") as f:
        f.write(png)
    print(f"saved edited.png ({len(png)} bytes)")

用回调代替轮询

轮询对脚本和 worker 队列没问题。对于 Web 后端，创建任务时注册回调，让 hiapi 把终态推给你——callback 对象位于请求顶层，紧挨着 model：

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

使用 "when": "final" 时，任务进入 success 或 fail 时你只会收到一次 POST。处理函数有两条规则：

• 使其具有幂等性。以任务 id 作为处理键，这样重复投递的 webhook 不会导致重复处理。在提交时存储任务 id，把回调视为“去获取并完成”的通知，而不是唯一的事实来源。
• 保留对账路径。如果回调触发时你的端点宕机，定期扫描未完成 id 并 GET /v1/tasks/<id> 可以捕获遗漏。

如果你的回调似乎一直没到，请按为什么你的 hiapi 任务回调没有触发中的常见故障模式按可能性顺序逐一排查。

错误处理：三种真正重要的失败

创建时的 401 permission_denied——你的密钥无法使用该模型。响应体形如：

{"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "type": "hiapi_error"}}

在控制台中检查密钥的模型权限，或使用已启用图像模型的密钥。

创建时的 400 INVALID_REQUEST——你的 input 与该模型的 schema 不匹配。消息会一次列出所有违规字段（例如 resolution: value must be one of '2K', '4K'; <root>: additional properties 'size' not allowed），所以要完整阅读并一次性修复所有字段。这些是永久性错误——重试相同 payload 将永远失败。

任务上的 status: "fail"——创建成功但生成失败（后端无法获取的参考 URL、内容策略、上游容量）。任务的 error.code 和 error.message 会说明原因。与 400 不同，其中一些是暂时性的，值得带退避重试一次。

还值得知道：GET 一个不存在或已过期的任务 id 会返回 404 task not found——在对账扫描中应把它视为终态，而不是“仍在等待”。

接下来去哪里

• seedream-5.0-lite/image-to-image 模型页——playground 和按图计费。
• hiapi 定价——所有图像模型的当前费率。
• 2026 年最佳图生图 API——在同一编辑任务上 seedream 与 gpt-image-2 等的比较。
• gpt-image-2 图生图教程——相同任务 API，不同 input schema；很好地说明为何 payload 不能在模型间通用。
• hiapi 文档——完整任务 API 参考。

FAQ

我可以向 seedream-5.0-lite 图生图传入多少张参考图？ image_urls 数组最多 14 张。最少一张——该字段必填，所以纯文生图调用应改用 seedream-5.0-lite/text-to-image。

为什么其他模型能用 1K，我却收到“value must be one of '2K', '4K'”？ 任务 API 的输入 schema 是按模型定义的。seedream-5.0-lite 的图生图模式只提供 2K 和 4K 输出；其他模型提供 1K 档位。不要不检查就复用另一个模型的 payload。

我可以用 base64 而不是 URL 发送参考图吗？ 该模型的 schema 接受 image_urls——一个 URL 数组。请把图片托管在可访问的 HTTPS URL 上（任何 CDN、对象存储桶或预签名 URL 都可以）并传入该 URL。

一次生成需要多久，输出 URL 有效期多长？ 通常远低于上面 Python 示例中 600 秒的轮询预算。输出 URL 带有 expireAt 时间戳——任务成功后立即下载字节并存入你自己的存储。

同样的代码能用于 seedream-5.0-lite 文生图吗？ 端点和流程相同，但文生图有自己的 input schema（没有 image_urls）。把模型 id 换成 seedream-5.0-lite/text-to-image 并去掉参考图——然后用一次测试调用验证，因为各模式的必填字段不同。

每张图多少钱？ 定价按每次生成用量计费，并因分辨率而异。请在定价页查看实时费率。