HiAPI
Zh
博客

教程

如何通过 hiapi API 使用 seedream-4.5/image-to-image：curl、Python 及可用请求

2026年11月3日
如何通过 hiapi API 使用 seedream-4.5/image-to-image：curl、Python 及可用请求

使用 seedream-4.5 编辑图像，只需向 hiapi 的统一任务 API 发送一个 POST、做一次短暂轮询，然后下载结果。本指南提供可用的 curl 请求和针对 seedream-4.5/image-to-image 的完整 Python 脚本，并给出精确的输入字段说明（已对照线上 API 验证）、多参考图用法，以及你实际会遇到的错误。

你将构建的内容以及所需条件

目标：将一张或多张源图加上编辑指令发送到 seedream-4.5/image-to-image，并取回完成的图像 URL。

前置条件：

  • 一个 hiapi API 密钥——从你的控制台获取。以下每个请求都用它作为 Bearer 令牌。
  • 源图托管在可公开访问的 URL 上。API 会在服务端抓取它们；本地文件路径或私有 URL 都不可用。

该模型运行在异步任务端点上：POST /v1/tasks 创建任务，GET /v1/tasks/<taskId> 报告状态，完成的图像出现在 data.output[0].url。

输入字段说明（已验证）

seedream-4.5/image-to-image 有四个必填输入字段，不接受其他字段——字段说明是严格的，未知字段会以 400 拒绝：

字段 类型 约束
prompt string 编辑指令
image_urls 字符串数组 公开 URL，最多 14 张图像
aspect_ratio string 1:1、4:3、3:4、16:9、9:16、2:3、3:2、21:9 之一
resolution string 仅 2K 或 4K

有两点值得注意：没有 n 参数（每个任务一个输出——如需多个变体，请并行创建多个任务）；并且不同于 seedream-5.0-pro 的 image-to-image（接受 1K/2K），4.5 要求 2K 或 4K。此处发送 1K 会返回校验错误。

最小可用请求：curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "input": {
      "prompt": "Turn this product shot into a clean studio photo on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

创建成功会在 data.taskId 返回任务 ID。轮询它：

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

当 data.status 达到 success 时，图像 URL 在 data.output[0].url。若为 fail，原因在 data.error。

完整 Python 脚本

不需要 SDK——只需 requests 和一个轮询循环：

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-4.5/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # public URLs, max 14
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,   # "2K" or "4K"
        },
    }, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["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()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]
            # 3. Output URLs expire -- download immediately
            return requests.get(url, timeout=120).content
        if task["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} did not finish in 600s")

png = edit_image(
    "Turn this product shot into a clean studio photo on a seamless white background",
    ["https://your-cdn.example.com/source.jpg"],
)
with open("edited.png", "wb") as f:
    f.write(png)

注意第 3 步的注释：输出 URL 带有过期时间戳。任务成功后应立即将字节持久化到你自己的存储——不要只保存返回的 URL 并指望它明天还能用。

多参考图编辑

image_urls 在一个任务中最多接受 14 张图像。这是风格迁移和构图任务的利器：传入你想编辑的图像以及参考图像，并在 prompt 中描述如何组合它们。

{
  "model": "seedream-4.5/image-to-image",
  "input": {
    "prompt": "Apply the color grading and lighting style of the second image to the first image, keep the subject unchanged",
    "image_urls": [
      "https://your-cdn.example.com/subject.jpg",
      "https://your-cdn.example.com/style-reference.jpg"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}

顺序对 prompt 有意义，对 API 没有——请按位置引用图像（"第一张图像"、"第二张图像"），这样模型才知道哪张是哪张。

生产环境注意事项

使用回调替代轮询。 对于脚本以外的任何场景，在创建任务时添加一个根级 callback 对象，完全跳过轮询循环：

{
  "model": "seedream-4.5/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

任务完成时，hiapi 会将任务的最终状态 POST 到你的 URL。轮询适用于 CLI 工具和 notebook；对于 Web 后端，回调才是正确选择，否则你将为一个 2K 编辑所需的几十秒一直占用一个工作进程。

幂等性。 任务创建不是幂等的——网络超时后重试创建可能产生（并计费）两个任务。拿到 taskId 的那一刻就存储它，重试时先检查是否已有活动任务，再创建新任务。

错误处理。 你最先会遇到的两类失败：

  • 401 permission_denied——密钥错误，或该密钥无权访问此模型。响应体类似 {"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "..."}}。联系支持时请附上 request_id。
  • 400 INVALID_REQUEST——字段说明违规，会给出精确消息：resolution 值错误、image_urls 超过 14 个、未知字段，或 image_urls 不是数组。这些都在任务运行前被捕获，因此不会产生费用。

失败的任务会在任务本身上报告 status: "fail" 并附带 error 对象——请将其作为与 HTTP 错误不同的情况处理，如上文 Python 脚本所做。

定价

每张图像的费用取决于分辨率。请在定价页面查看当前费率。在校验阶段被拒绝的请求（400）永远不会启动任务，因此集成期间字段说明错误是免费的。

相关阅读

常见问题

我可以传入本地文件或 base64 图像而不是 URL 吗？ 不可以。image_urls 必须是可公开访问的 URL 数组——平台会在服务端抓取并规范化它们。请先上传到你自己的存储（S3、R2、任意 CDN），再传入 URL。

seedream-4.5 image-to-image 支持多少张参考图？ 每个任务最多 14 张。超出会返回 400，消息中包含 image_urls: maxItems。

为什么我把 resolution 设为 1K 时会收到 400？ 4.5 image-to-image 端点只接受 2K 或 4K。1K 选项属于 seedream-5.0-pro 的 image-to-image——不同层级系列的枚举不同。

我可以在一个请求中生成多个变体吗？ 不可以——字段说明中没有 n 参数，并拒绝未知字段。请为每个变体创建一个任务并并行运行；每个任务只返回一个输出。

结果 URL 的有效期是多久？ 输出 URL 带有签名和过期时间。任务成功后应立即下载图像并自行存储，而不是热链接任务输出。

HTTP 错误和失败任务有什么区别？ HTTP 错误（400/401）表示请求从未成为任务——修正载荷或密钥后重新发送。以 status: "fail" 结束的任务已被接受但无法完成；原因在任务的 error 对象中，对于瞬态失败，使用相同输入重试通常是正确做法。

标签Image APITutorialimage-to-image

相关文章

查看全部文章 →

立即开始构建持久 AI 产物

获取 API 密钥，通过一个基于任务（task）的 API 调用图像、视频和音频模型。

阅读 API 文档