Seedream 5.0 Pro 文生图 API 接入教程

Seedream 5.0 Pro 文生图（seedream-5.0-pro/text-to-image）是 Seedream 5.0 家族里最贵的一档，强项是图里的文字：招牌、包装、海报标题照着提示词逐字写。这篇给出能直接跑的 curl 和 Python 示例、全部参数、常见报错，以及让文字写对的几个办法。

先看价格

分辨率	每张	100 张
1K	$0.05	$5
2K（默认）	$0.10	$10

HiAPI 现价，2026 年 10 月 18 日核对。

画幅不影响价格，失败不扣费。Pro 没有 4K；要 4K 可以用 Seedream 5.0 Lite（2K/4K 同价 $0.035）。三档对比见 Seedream 5.0 API 价格。

一张真实出图

16:9，1K，霓虹招牌上的字逐字写对：

A neon-lit night market street in a rainy cyberpunk city, a glowing storefront sign reads "SEEDREAM 5 PRO" in crisp lettering, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range

用这条提示词生成 →

seedream-5.0-pro/text-to-image，16:9，1K，$0.05。

跑通第一张

准备：在控制台创建 API Key，设成环境变量：

export HIAPI_KEY="你的 Key"

curl：提交任务

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
      "prompt": "A cozy coffee shop storefront at dusk, warm window light, a hand-painted wooden sign that reads \"THE DAILY GRIND\" in serif letters",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

返回 taskId：

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl：查结果

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-..." \
  -H "Authorization: Bearer $HIAPI_KEY"

data.status 为 success 时，图片地址在 data.output[0].url。这是带过期时间的临时链接，拿到就下载：

curl -o result.png "<output 里的 url>"

2K 一般一分钟左右出图。

Python（只用标准库）

import json, os, time, urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = os.environ["HIAPI_KEY"]

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

task_id = api(API, {
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
        "prompt": 'A minimalist product poster on matte black, bold white headline that reads "SHIP FASTER", small caption "batch v2.1" bottom right',
        "aspect_ratio": "3:4",
        "resolution": "2K",
    },
})["data"]["taskId"]

while True:
    task = api(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        raise RuntimeError(task)
    time.sleep(5)

urllib.request.urlretrieve(task["output"][0]["url"], "result.png")

全部参数

字段	必填	取值
`prompt`	是	3–4000 字符，建议控制在约 600 个英文词以内
`aspect_ratio`	是	`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`2:3`、`3:2`、`21:9`
`resolution`	是	`1K`（$0.05）或 `2K`（$0.10）
`output_format`	否	`png`（默认）或 `jpeg`

字段很严：seed、n、size、image_urls 这些都不收，多传会返回 HTTP 400。一次请求出一张，要多张就并发提交多个任务。

同家族各档的分辨率不一样：Pro 是 1K/2K，Lite 是 2K/4K。跨档切换时记得改 resolution。

让文字写对

要写的字用引号括起来：a sign that reads "OPEN 24 HOURS"，比转述可靠得多。
写清位置和样式：字体感觉（衬线、手写、霓虹）、位置（右下角、居中）、载体（木牌、玻璃门）。
字别太多：一张图几处短文字很稳，大段文字不稳。
文字是重点就用 2K：小字在高分辨率下更清楚。

常见报错

现象	返回	怎么改
少传必填字段	400，`missing required field "aspect_ratio"`	三个必填字段都要传
枚举值不对	400，`resolution: value must be one of '1K', '2K'`	按上面的表填
多传 `seed`、`n` 等	400，`additional properties ... not allowed`	删掉多余字段
Key 无效	401，`permission_denied`	去控制台检查 Key

任务建好之后失败的，在查询结果里是 status: "fail"，不扣费。

上线前注意

用回调代替轮询：请求体顶层（和 model、input 同级）加 "callback": {"url": "https://你的域名/hooks/hiapi", "when": "final"}。收到通知后再 GET 一次任务确认结果。
防重复扣费：任务一受理就计费。重试前先查自己有没有记下这个任务的 taskId，有就继续查，不要重新提交；也可以提交时带 Idempotency-Key 请求头。
及时转存：输出链接会过期，不要直接外链。