教程

如何通过 hiapi API 使用 seedream-5.0-pro/image-to-image：curl、Python 以及一个可运行的请求示例

2026年11月3日

Seedream 5.0 Pro 是字节跳动的旗舰图像模型，其图像到图像（image-to-image）端点接收一张或多张参考图像以及一段文本指令，返回编辑后的结果——重绘风格、更换背景、产品图清理、多图合成。在 hiapi 上，它运行在统一的异步 tasks API 之上：你先创建任务，然后轮询（或接收回调），最后下载输出。下文中的每个参数、枚举值和错误消息都已在本指南发布前对照线上 API 验证过。

你将构建什么，以及需要准备什么

目标：向 seedream-5.0-pro/image-to-image 发送一张参考图像和一条编辑指令，取回编辑后的图像并保存到本地。

你需要准备两样东西：

一个 hiapi API 密钥 —— 从你的控制台获取。它需要放在 Authorization: Bearer sk-... 请求头中。
可公开访问的图像 URL —— API 会在服务端抓取你的参考图像，因此它们必须能通过 HTTPS 访问。你自己的存储桶生成的预签名 URL 完全可用；localhost 或私有路径则不行。如果 URL 无法抓取，你会收到规范化错误，而不是静默失败。

参数（已验证）

模型 ID 为 seedream-5.0-pro/image-to-image，与 GET /v1/models 返回的完全一致。全部四个输入字段均为必填：

字段	类型	必填	取值 / 说明
`prompt`	string	是	编辑指令。
`image_urls`	字符串数组	是	1–10 个可公开访问的图像 URL。始终为数组，即使只有一张图像。
`aspect_ratio`	string	是	`match_input_image`、`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`、`21:9`
`resolution`	string	是	`1K` 或 `2K`

有两个容易出错的地方：

Schema 是严格的。未知字段会被拒绝——发送 n、size 或 seed 会返回 400，并附带 additional properties ... not allowed。hiapi 上每个模型的输入 schema 各不相同（有些模型使用 size，有些使用 aspect_ratio），因此不要跨模型家族复制字段。
此处的 resolution 仅支持 1K/2K。其他 seedream 端点接受不同的分辨率集合，因此值得按端点逐一确认，而不是想当然。

最小可运行示例：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-5.0-pro/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

创建成功时，任务 ID 会在 data.taskId 中返回（响应已简化）：

{ "data": { "taskId": "<your-task-id>" } }

轮询直到任务进入终态：

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

data.status 最终为 success——你的图像 URL 位于 data.output[0].url——或 fail，详细信息在 data.error.code 和 data.error.message 中。

完整的 Python 脚本：创建、轮询、下载

仅使用标准库——无需安装任何东西：

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the edit task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

生产环境注意事项

在服务器上，优先使用回调而非轮询。创建任务时添加一个顶层 callback 对象，hiapi 会在进入终态时向你的端点 POST 一次：

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

在处理程序中，把回调当作信号，而不是事实来源：从中取出任务 ID，然后自己重新请求 GET /v1/tasks/<id>，再据此采取行动。对于脚本、notebook 和一次性任务，轮询仍然是合适的选择——只需将间隔保持在 5 秒左右。

使重试具备幂等性。创建任务时，保存你自己的源图像 → taskId 映射。如果进程在轮询中途崩溃，应重新关联到已保存的 taskId，而不是重新提交编辑——重新提交会产生第二个计费任务。

立即下载输出。data.output[0].url 中的 URL 有时间限制（带有过期时间）。请下载字节并存储到你自己的存储桶中；绝不要在面向用户的内容中直接热链任务输出 URL。

你实际会遇到的错误：

401 附带 permission_denied —— API 密钥缺失或格式错误。检查请求头是否准确为 Authorization: Bearer sk-...。
400 附带 INVALID_REQUEST —— 输入 schema 违规。错误消息很精确，例如 resolution: value must be one of '1K', '2K' 或 image_urls: maxItems: got 11, want 10。
image_urls must be an array —— 你传入了裸字符串。即使只有一张图像，也要将其包裹在列表中。

下一步

模型页面：seedream-5.0-pro/image-to-image —— 能力与当前状态。
每张图像的价格列在定价页面上。
高并发流水线的更便宜编辑方案：如何使用 seedream-5.0-lite 图像到图像。
在模型之间做选择：2026 年最佳图像到图像 API 在三个模型上比较了相同的编辑任务。
完整 API 参考：hiapi 文档。

常见问题

最多可以发送多少张参考图像？ image_urls 中最多 10 个 URL。该限制在服务端强制执行——11 张图像会返回 maxItems: got 11, want 10。

输出能否保持输入图像的宽高比？ 可以——将 aspect_ratio 设为 match_input_image。对于编辑和重绘，这通常是你想要的；只有在你刻意重新构图时，才选择像 16:9 这样的明确比例。

seedream-5.0-pro image-to-image 支持 4K 吗？ 不支持。此端点仅接受 1K 和 2K。如果你请求其他任何值，会收到 400 并列出允许的值。

我的图像 URL 必须是公开的吗？ 它们必须能被 hiapi 的服务器通过 HTTPS 抓取。预签名 URL（S3、R2、GCS）效果很好，并且可以让你保持存储桶本身私有。

seedream-5.0-pro image-to-image 每张图像的费用是多少？ 定价按成功生成的图像计费，并因分辨率而异——请查看实时定价页面了解当前费率。

这与 seedream-5.0-lite image-to-image 有何不同？ Pro 是旗舰层级，面向更困难、更高保真度的编辑；lite 是更快、更便宜的大批量选项。请求结构相似，因此最清晰的判断方式是用相同的编辑任务分别跑一遍——从lite 指南开始，并将结果与你自己的参考图像进行比较。