教程

如何通过 HiAPI API 使用 recraft-v4.1/text-to-image：curl 与 Python 指南

2026年11月3日

此端点能为你提供什么

recraft-v4.1/text-to-image 是一个文生图模型端点：你在请求体中发送文本提示词以及若干塑形选项，然后得到生成的图像数据。当你希望一次调用就能产出成品图像、而不必自行编排多步流水线时，它非常合适。

在 HiAPI 上，该模型纳入聚合模式：一个基础 URL、一个认证头，以及跨端点一致的请求/响应结构。你不必为每个要评估的图像模型分别接入 SDK 和凭据集，只需将客户端指向 HiAPI 上 recraft-v4.1/text-to-image 的端点，其余代码保持稳定。这在原型阶段尤为重要——你希望比较提示词、风格和模型，而不必每次都重写传输层。

理解该调用的一种实用方式：

Prompt —— 你想要的图像的自然语言描述。
Style —— 请求体字段，用于引导输出的视觉处理方式。
Resolution —— 请求体字段，用于决定输出尺寸。

因为三者都在同一个 JSON 体中传输，提示词工程与输出塑形在一次往返中完成。如果你在判断这是否是合适的端点，答案通常是肯定的——当你需要同步的、提示词驱动的图像生成，并且希望把供应商管路细节排除在应用代码之外时。

前置条件与认证

在首次调用之前，请确保你具备：

一个 HiAPI 账户和 API 密钥。请将其排除在源码控制之外，并从环境变量加载。
用于快速冒烟测试的 curl，以及安装了 requests 的 Python 3（如果你打算使用 Python 示例）。
一个你确实想要渲染的提示词——即使粗糙也足以验证接线是否正确。

HiAPI 的认证基于请求头。API 密钥通过请求头传递，无论你从 curl、Python 还是其他 HTTP 客户端调用，都使用相同的请求头模式。模型选择通过端点路径完成，因此在你切换模型时，认证头保持不变。

安全的本地设置如下：

export HIAPI_API_KEY="your-key-here"

然后在 shell 命令中引用 $HIAPI_API_KEY，在 Python 中引用 os.environ["HIAPI_API_KEY"]。切勿将密钥硬编码到可能被提交的脚本中，也避免将其粘贴到日志或错误报告中。如果密钥泄露，请在账户设置中轮换它，而不是试图从历史记录中清除。

以下示例假设两件事：HiAPI API 的基础 URL，以及 recraft-v4.1/text-to-image 的模型路径。在将其接入构建之前，请对照你账户的 API 参考确认这两者，因为确切的主机和路径是本指南中唯一应当从当前文档而非凭记忆复制的内容。

可运行的 curl 请求

确认密钥、端点和载荷结构都能正常工作的最快方式是一次 curl 调用。该请求发送包含提示词和塑形字段的 JSON 体，并在请求头中传递 API 密钥：

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

关于此调用，有几点需要注意：

端点路径。 模型名称位于路径中。之后换用其他模型意味着更改该路径段，而不是重建请求。
用请求体，而非查询字符串。 prompt、style 和 resolution 都放在 JSON 体中。这样 URL 保持稳定，载荷也易于记录和重放。
请求头认证。 Authorization 头携带密钥；Content-Type 必须为 application/json。

如果首次尝试就收到非 200 响应，请按以下顺序检查：密钥是否已在 shell 中设置、基础 URL 是否没有重复的尾部斜杠、JSON 体是否有效（尾随逗号通常是罪魁祸首）。一旦调用成功，请将确切的命令保存到草稿文件中——一个已知可用的 curl 调用是你对比每次 SDK 和客户端更改的参照。

同样的请求在 Python 中

对于真实代码，请将调用封装在一个小函数中，以便重试、日志记录和模型切换有统一的存放位置。使用 requests：

import os
import requests

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

值得保留的设计要点：

用 json= 而非 data=。 向 json= 传递 dict 会为你设置内容类型并序列化请求体，因此载荷与 curl 版本逐字节一致。
显式超时。 图像生成不是瞬时的；宽松的超时可以避免因缓慢但健康的请求而误报失败。不要依赖客户端默认值。
先 raise_for_status()。 在尝试读取响应体之前将 HTTP 错误转换为异常，这样 4xx 或 5xx 绝不会被误认为图像数据。
环境驱动的配置。 基础 URL 和密钥都来自环境，这使函数在本地、预发和生产环境之间可移植。

函数返回解析后的 JSON。如何从该 JSON 中提取图像是下一个话题，也是大多数集成出错的地方。

处理同步图像响应

recraft-v4.1/text-to-image 同步返回图像数据：图像随请求在同一个 HTTP 响应中返回，没有轮询循环，也没有需要跟踪的任务 ID。这简化了客户端，但将两项职责转移到你的代码上——解码载荷和显式处理失败。

稳健的处理路径如下：

解析前检查状态。 将任何非 200 视为错误，并显示响应体，这通常能解释问题所在。
有意识地读取图像字段。 响应 JSON 携带图像数据；根据你收到的字段，它可能是 URL 或编码后的图像字节。请处理两种路径，而不是假设其中一种。
防御性解码。 如果载荷是 base64 编码的，请解码并将字节写入文件。不要通过仅限文本的路径路由二进制数据，也不要将其打印到终端。
限制载荷大小。 与典型 JSON 相比，同步图像响应很大。在客户端支持的情况下流式写入磁盘，并避免同时在内存中保留多个响应。

针对 base64 载荷的最小保存步骤：

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

两种失败模式值得专门处理。超时应使用退避重试，但仅适用于幂等预期——重新生成图像会产生不同结果，因此每次尝试都要记录提示词。客户端错误（如请求体格式错误或选项值无效）不会因重试而自行修复；应快速失败并记录响应文本。最后，在解码前验证图像字段存在，这样模式变更或错误载荷会引发清晰的异常，而不是令人困惑的解码错误。

为你的用例调整风格与分辨率

style 和 resolution 是对返回结果影响最大的两个请求体字段，且两者迭代成本低，因为它们随提示词一同传递。

Style

style 引导输出的视觉处理方式。用它来保持一系列图像的风格一致——例如，在一批产品插图或文章头图中固定同一种风格，使它们看起来像一套。当结果感觉不对时，首先检查风格是否与内容匹配：将面向插图的风格应用于写实提示词会与文本冲突。在添加细节之前，先用固定风格尝试简单提示词，这样你就能判断糟糕的结果是来自风格还是措辞。

Resolution

resolution 决定输出尺寸。使其与目标用途匹配：头像和缩略图选择接近正方形的尺寸，横幅和主图选择更宽的尺寸。两条实用规则：

能请求的就不要放大。 直接生成接近最终显示尺寸的图像，而不是生成小图再放大。
注意宽高比。 如果你的布局期望特定比例，请选择匹配该比例的分辨率，而不是事后裁剪。

调试意外输出

当图像看起来不对时，一次只隔离一个变量。保持提示词不变，改变 style；然后保持两者不变，改变 resolution。如果都无济于事，请用具体名词和明确的构图线索重写提示词，而不是添加形容词。同时确认你没有在悄悄发送错误的值类型——与可接受选项不匹配的风格字符串可能被拒绝或被忽略，具体取决于验证逻辑。记录每次调用的确切请求体；这是某张图像由何产生的唯一可靠记录。

为生产环境封装

前面那个小函数的价值在你加固它时显现出来。生产级封装应做四件事：

封装传输。 一个函数拥有 URL、请求头、载荷结构和超时。调用者只传递提示词和选项，别无其他。
添加带退避的重试。 对超时和 5xx 响应进行有限次数的重试；绝不重试 4xx 错误。由于图像生成不是幂等的，请将重试上限设低，并让提示词与每次尝试保持关联。
记录请求，而不仅仅是结果。 记录提示词、风格、分辨率、状态和持续时间。当有人问为什么图像看起来是这样时，该日志就是答案。
将模型作为参数。 将模型路径作为参数传入，默认值为 recraft-v4.1/text-to-image。这样切换到另一个图像模型就变成了配置更改而非重构，从而使并排评估成本低廉。

保持封装层轻薄。抵制在其中添加缓存、排队或存储策略——那些属于上一层，以便它们能独立于 API 调用演进。稳定的接口也意味着你的测试可以模拟传输层并断言你将发送的载荷，这能在大多数集成错误到达真实请求之前将其捕获。

有了认证、已知可用的请求和显式的响应处理，你就具备了从 HiAPI 以 curl 和 Python 调用 recraft-v4.1/text-to-image 所需的一切，并且之后可以在不触碰其余代码的情况下切换模型。

查看全部文章 →