如何通过 hiapi API 使用 seedream-5.0-flash：curl、Python 和可运行的请求

你将构建的内容

一个可运行的集成，从 curl 和 Python 调用 hiapi 的 seedream-5.0-flash 图像模型：提交文生图（或图像编辑）请求、轮询结果并下载输出 URL。到最后你将得到一个可以直接放入自己项目的脚本。

前提条件

• 一个 hiapi 账号和 API 密钥。从 hiapi 控制台 获取 — 密钥形如 sk-...。
• curl 或 Python 3.8+（pip install requests）。
• 无需图像编辑库 — seedream-5.0-flash 接受纯提示词，或提示词加一个用于编辑的输入图像 URL。

完整模型参考：hiapi 上的 seedream-5.0-flash 和 API 文档页。

最小可运行示例

hiapi 通过一个统一端点暴露所有生成模型：你先创建任务，然后轮询它（或接收回调）直到完成。

curl

# 1. 创建任务
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. 轮询直到完成
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

关于 input 对象的说明：

• prompt（必填，1–5000 字符）— 要生成什么，或如果你同时传入 image，则要修改什么。
• image（可选，字符串或最多 10 个 URL/base64 data:image/... URI 的数组）— 传入此参数可编辑/参考现有图像，而不是从零生成。纯文生图时省略。
• size（可选，默认 "2K"）— 预设值之一 1K / 1.5K / 2K，或自定义 WIDTHxHEIGHT 字符串如 "1536x1024"（总像素 921,600–4,624,220，宽高比在 1:16 到 16:1 之间）。
• output_format（可选）— "jpeg" 或 "png"。
• background（可选，默认 "opaque"）— 仅当编辑带 alpha 通道的图像时才设为 "transparent"。

响应中的 output[].url 是带签名、会过期的链接（expireAt 字段）— 请及时下载或重新托管，而不是长期保存这个热链接。

生产环境模式

使用回调代替轮询

对于服务器到服务器的集成，跳过轮询，让 hiapi 在任务完成时通知你。在 model/input 旁边添加一个顶层 callback 对象（不要嵌套在 input 内）：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" 目前是唯一支持的值 — 当任务到达终态（success 或 fail）时，你的端点会收到恰好一次 POST。为防投递重试，请按 taskId 去重，并在生产环境依赖它之前确认你的端点可通过 HTTPS 访问。

轮询 vs. 回调

• 当你做原型、运行短生命周期脚本或还没有公共 HTTPS 端点时，用轮询。简单，但会增加延迟和慢任务的请求量。
• 当你运行服务时用回调 — 没有浪费的轮询请求，任务一完成你就能立即知道。需要公开可访问的 HTTPS URL。

幂等性

图像生成本身不是幂等的（相同的提示词不会两次返回相同的图像），所以如果你的工作流需要"重试不重复收费"语义，请在你这边跟踪 taskId，并在超时后重新提交相同请求前检查任务状态，而不是盲目重试。

错误处理

• 401 伴随 permission_denied — 你的 API 密钥缺失、格式错误或被撤销：

  {"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}
  

  仔细检查你发送的是 Authorization: Bearer sk-...（而不是仅原始密钥），并且密钥未被轮换。

• 400 伴随 INVALID_REQUEST — 某个字段未通过验证。message 会准确告诉你哪个字段以及原因，例如超出范围的 size。修复该字段并重新提交；不要原样重试。

• 任务级失败 — HTTP 调用可能成功（200），而任务在处理完成后仍以 status: "fail" 结束。始终检查轮询/回调响应中的 data.status，而不仅仅是创建调用的 HTTP 状态码。

相关内部链接

• seedream-5.0-flash 模型页 — 价格、限制和在线试用面板。
• 创建任务（文档） — POST /v1/tasks 的完整请求架构。
• 获取任务详情（文档） — 轮询响应结构和状态值。
• 认证（文档） — API 密钥和请求头在所有 hiapi 端点上的工作方式。
• hiapi 价格 — seedream-5.0-flash 及所有其他模型的当前每图价格。
• seedream-5.0-pro 文生图 API 指南 — 如果你需要更高分辨率输出，请参阅 Pro 层更高保真的兄弟模型。

常见问题

seedream-5.0-flash 免费吗？ 不免费 — 它通过你的 hiapi API 密钥按图计费。当前费率见价格页；没有有效密钥就无法进行生产访问。

seedream-5.0-flash 支持图生图编辑，而不仅仅是文生图吗？ 支持。在 prompt 旁边添加 image 字段（URL 或 base64 data:image/... 字符串，或最多 10 个的数组），模型将基于参考图像进行编辑/融合，而不是从零生成。

为什么我的请求返回 200 但没有图像？ POST /v1/tasks 返回 200 仅意味着任务已被接受 — 生成是异步的。轮询 GET /v1/tasks/<id>（或等待回调）并检查 data.status；图像 URL 仅在 status 为 "success" 时出现。

我可以请求自定义分辨率而不是 1K/1.5K/2K 吗？ 可以 — 将 size 传为 "WIDTHxHEIGHT"（例如 "1536x1024"）而不是预设值。总像素必须在 921,600 到 4,624,220 之间，宽高比在 1:16 到 16:1 之间，否则请求返回 400。

一段时间后输出 URL 会怎样？ 返回的 output[].url 是带 expireAt 时间戳的签名 URL — 它不是永久存储。任务成功后请尽快下载字节或将它们复制到你自己的存储中。

我的回调从未触发 — 我应该先检查什么？ 确认你的 callback.url 是可公开访问的 HTTPS 端点（不是 localhost 或仅内部地址），并且 callback 是请求体中的顶层字段 — 而不是嵌套在 input 内。