博客

教程

如何通过 HiAPI API 使用 seedream-4.5/text-to-image:curl 与 Python 示例

面向开发者的最小可运行集成实操指南

2026年11月17日
hiapi.ai 博客封面图:暖灰混凝土平面在斜射日光下交错,深蓝灰阴影面与细鼠尾草绿接缝构成极简几何构图。
本页内容

seedream-4.5/text-to-image 能为你提供什么

seedream-4.5/text-to-image 是通过 HiAPI API 提供的文生图端点。你发送一段文本提示词和几个可选参数,模型返回一张生成的图像。你可以用它来创建场景插画、产品样机图、概念艺术,或任何需要在图像内渲染可读文字的视觉内容——招牌、标签、短标题。该端点是无状态的:每次请求都是独立的一次生成,因此重复与变化的控制权在你的应用代码中。

由于它与其他 HiAPI 模型运行在同一个统一接口之后,你只需认证一次,使用相同的基础 URL 和错误约定,并且切换模型时无需学习新的集成模式。seedream-4.5/text-to-image 的模型详情页列出了当前的参数名和可接受值——请以该页面作为字段的权威来源,而非本文。

请求结构:发送与接收的内容

每次文生图调用都有相同的结构:向模型的 HiAPI 端点发送一个带有 JSON 请求体的 POST 请求。请求体包含模型所需的字段;响应包含生成的图像和关于该请求的元数据。

发送的内容

  • prompt(字符串,必填):图像的描述。这是主要的控制面;参见下方提示词部分。
  • aspect_ratio 或某个与尺寸相关的字段(可选):控制输出画布的形状。请使用模型详情页中的确切字段名——不要假定它与其他模型的参数名一致。
  • 模型页面记录的任何模型专属选项(例如风格或质量提示)。省略你不需要的字段;API 会应用默认值。

接收的内容

成功的响应是一个 JSON 对象。你在代码中实际会读取的字段通常是:

  • 图像载荷:根据响应模式,可能是生成图像的 URL,也可能是 base64 编码的图像字符串。你的代码应处理端点实际返回的形式;模型页面会说明是哪种。
  • 请求元数据,例如标识符或状态,对日志记录和支持很有用。

并非每个字段在所有版本中都有保证,因此应校验响应结构,而非假定一个固定的 schema。如果你构建的解析器只查找你需要的字段,并将其他字段视为可选,你的集成就能经受住轻微的响应变化。

你的第一个可运行的 curl 请求

最小的有效调用只发送一个提示词,别无其他。将占位符密钥和提示词替换为你自己的,然后运行它。

curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "黄昏时分一家安静的街边咖啡馆,温暖的窗光,一块写着 OPEN 的黑板招牌",
    "aspect_ratio": "1:1"
  }'

逐行说明:

  • URL 指向该模型的 HiAPI 端点。保持模型标识符与文档完全一致。
  • Authorization 头携带你的 API 密钥。使用环境变量可以让密钥不出现在你的 shell 历史和源文件中。
  • Content-Type: application/json 告诉服务器将请求体按 JSON 解析。
  • JSON 请求体包含提示词和一个可选的宽高比。先从一张图像和一个提示词开始;在添加选项之前先迭代措辞。

如果调用成功,响应会包含上一节描述的图像数据。将输出保存到文件(或打开返回的 URL)并在构建更多内容之前检查它。如果遇到认证错误,确认密钥存在且头部拼写正确;如果遇到参数错误,对照模型页面重新检查字段名。

用 Python 实现同样的请求

Python 版本使用标准的 requests 库——无需 SDK。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"

payload = {
    "prompt": "黄昏时分一家安静的街边咖啡馆,温暖的窗光,一块写着 OPEN 的黑板招牌",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)

这里有两个细节很重要。第一,传入 json=payload 而不是手工构建的字符串——requests 会设置内容类型并正确序列化。第二,设置显式的 timeout。图像生成可能比典型的 API 调用耗时更长,因此带有明确失败模式的宽松超时比挂起的请求更好。

打印的结果是原始响应。在实际代码中,提取你的端点返回的图像字段(URL 或 base64),然后要么用第二个请求下载该 URL,要么将 base64 解码为字节并写入磁盘。将该提取逻辑放在一个小型辅助函数中,使测试与生产代码共享相同的解析逻辑。

为写实效果与可读文字编写提示词

提示词质量比其他任何参数都更能决定输出质量。最常出现的两个目标是:照片级写实的场景和图像内清晰可读的文字。

写实效果

像摄影师取景那样描述场景:主体、光线、时段、镜头感以及环境。具体的名词胜过抽象的形容词。不要写“一家不错的咖啡店”,而要写“一家狭长的咖啡店内部,正午的光线透过大窗户照入,木质柜台,浅景深”。添加一个简短风格提示,例如“photograph”或“documentary photo”,以引导模型远离插画风格。每个提示词保持一个主要主体;相互竞争的主体往往会产生混乱的构图。

可读文字

当图像必须包含文字时,将确切的文字放在引号中并保持简短。一块写着 OPEN 的招牌或一个写着 FRESH BREAD 的标签,远比一整段文字可靠。说明文字出现的位置——“柜台上方一块写着 OPEN 的黑板招牌”——这样模型就知道该文字属于某个物体。如果文字出现乱码,就缩短它、简化周围场景并重新生成。小幅调整措辞是正常的;预期需要几次迭代。

迭代

一次只改变一个变量:先改提示词,再改宽高比,最后改任何风格选项。保存你的提示词以及产生良好结果的设置。这份记录将成为你的重新生成基线,并防止调试沦为猜测。

选择宽高比与输出设置

宽高比在模型绘制任何内容之前就决定了构图。应根据目标用途来选择,而不是为了匹配默认值。

  • 正方形(1:1):社交帖子、头像、产品图块。简单且安全。
  • 横向(例如 16:9):横幅、主视觉图、演示幻灯片。鼓励使用宽阔的场景——地平线、店面、宽敞的室内。
  • 纵向(例如 9:16):移动端屏幕、快拍、海报。具有清晰垂直主体的提示词——站立的人物、高耸的建筑——效果最佳。

如果你的提示词描述的是宽阔场景,但你请求的是纵向画布,模型就不得不裁剪或扭曲构图。让描述与画幅相匹配。对于下游流水线,按适合你最大用例的尺寸生成,之后再缩小;对小图像进行放大很少看起来正确。当你需要多种格式时,按每种比例分别发起调用,而不是将一张图像裁剪成各种布局。

宽高比之外的输出设置(质量提示、风格控制)是模型专属的。只设置模型页面记录的内容,并将每个额外参数视为需要测试的变量,而不是要照搬的默认值。

处理错误与速率限制

生产集成的失败原因是可以预见的:密钥错误、参数无效、超时以及限流。显式地处理每一类。

解析之前先校验

首先检查 HTTP 状态码。2xx 表示成功——然后解析响应体。4xx 通常意味着你的请求有问题:密钥未授权、JSON 格式错误或参数值不受支持。这些问题不会在重试后自行解决;记录响应体,将其上报给调用方,并修复请求。5xx 表示服务器端问题,通常是暂时性的。

带退避的重试

只重试那些之后可能成功的失败:429 响应、超时、连接错误以及大多数 5xx 状态码。使用带抖动的指数退避——等待一个较短的基准间隔,每次尝试翻倍,并设置总尝试次数上限。绝不要重试 400 或 401;你只会白白消耗配额。

import time, random

def generate(payload, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
        except requests.RequestException:
            pass  # 网络错误:在下方重试
        else:
            if r.status_code == 200:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                raise RuntimeError(f"不可恢复:{r.status_code} {r.text}")
        time.sleep(min(2 ** attempt + random.random(), 30))
    raise RuntimeError("重试次数耗尽")

遵守限制

将请求量保持在你账户所示速率限制之下,并将 429 视为放慢速度的信号,而非更用力重试的信号。在 worker 中添加上限并发数,并为每次尝试记录请求 ID,以便事后诊断限流和失败。由于图像调用按生成的输出计费,产生图像的重试并非免费——在发起请求前先校验输入。

从测试调用到生产检查清单

在上线前,确认以下运维要点:

  • 密钥管理:密钥存放在环境变量或密钥管理器中,绝不放源代码控制。按计划轮换密钥,并在任何疑似泄露时立即轮换。
  • 超时:每个出站调用都有显式超时,且你的调用方对超时触发时的处理有预案。
  • 日志记录:为每次调用记录请求 ID、提示词版本、参数、状态和延迟。在需要时对密钥和完整载荷进行脱敏。
  • 提示词版本化:保存提示词以及产生被接受输出的设置,以便重现和回滚。
  • 成本意识:生成按输出计费,因此限制批处理大小、避免不必要的重试,并缓存你将复用的结果。
  • 优雅降级:当重试后生成仍然失败时,回退到缓存的图像或占位符,而不是破坏页面。

从本指南中的单个 curl 调用开始,将其移入一个小型 Python 辅助函数,然后才添加并发和批处理。在扩展集成时,seedream-4.5/text-to-image 的模型参考页是确认字段名的地方。

立即开始构建持久 AI 产物

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

阅读 API 文档