博客

教程

如何通过 HiAPI API 使用 krea-3/text-to-image:curl、Python 与一个可运行的请求

2026年11月10日
封面图:暖炭灰底上有一道斜贯画面的琥珀色光带,边缘点缀细窄的辅色线条。
本页内容

为什么通过聚合 API 调用 krea-3/text-to-image

每出现一个新的图像模型,就意味着又一个 SDK、又一套认证方案、又一组响应怪癖。如果你只发布一个图像功能,这种成本尚可忍受。但如果你要发布多个——或者希望日后能自由替换模型——它就会成为工作中的主要成本。

通过 HiAPI 调用 krea-3/text-to-image 可以消除这笔成本。你只需针对单一端点约定、单一凭证和单一响应结构集成一次。模型标识符变成请求负载中的一个字段,而不是代码库中的一个分叉。当你想将输出与其他图像模型对比,或迁移工作负载时,你改的是一个字符串,而不是一次集成。

对于这个特定模型,实际收益是具体的:

  • 所有请求共用同一种结构。 文生图调用在整个平台上遵循相同的认证和负载约定,因此你从第一次调用中获得的知识可以直接迁移到下一个模型。
  • 与模型无关的应用代码。 将模型名称保留在配置中。针对 krea-3/text-to-image 做原型开发,之后切换到其他模型提供服务时,不应需要改动你的 HTTP 层。
  • 统一的用量观测入口。 计费、请求日志和错误响应都来自同一个界面,而不是 N 个供应商仪表盘。
  • 更少的密钥。 无论你调用多少个模型,只需存储、轮换和限定一个密钥。

代价是聚合的常见代价:你通过一个通用接口工作,因此模型特有的怪异之处被归一化了。在实践中,这正是你想要的——归一化的输入、可预测的错误,以及将模型视为可调参数的自由。

本教程刻意保持范围狭窄。我们将构建一个可运行的请求,运行两次(先用 curl,再用 Python),观察提示词措辞如何引导摄影风格与插画风格的输出,然后调试那些占首次调用问题大多数的少数失败情况。没有架构图,没有框架观点——只有一个你可以在接下来五分钟内发送的请求,以及一份出错时使用的检查清单。

前提假设:你拥有 HiAPI 账户,可以从仪表盘读取 API 密钥,并且熟悉终端和 Python 解释器。无需其他条件。

发送请求之前

首次调用之前需要满足三个条件。把这些做对,剩下的大多是调优;做错了,你就会花一个小时调试错误的层面。

1. 账户和 API 密钥

登录 HiAPI 并从仪表盘获取你的 API 密钥。将其视为机密:它应存放在环境变量或密钥管理器中,绝不能出现在提交的文件里,也绝不能出现在提示词或支持消息中。下面的示例从环境变量读取它:

export HIAPI_API_KEY="your-key-here"

如果你的组织支持多个密钥,请为此集成使用专用密钥,以便你可以独立于其他运行项轮换它。

2. 端点约定和认证头

HiAPI 请求使用 bearer token 认证——与你在其他上百个 API 中见过的模式相同:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

使用 HiAPI API 参考中为你账户区域显示的 base URL,并追加其中记录的图像生成路径。不要凭记忆或从博客文章(包括本文)猜测路径——API 参考是唯一事实来源,而路径是请求中唯一会无预警变化的部分。教程建议:查阅一次参考,复制 URL,并将其保存在配置值中。

3. 模型标识符,拼写完全一致

模型标识符是 krea-3/text-to-image。保持命名空间前缀和连字符与书写完全一致——krea3/text2image 或单独的 krea-3 都会因模型未找到而失败。大小写也很重要。将其存储为常量:

MODEL = "krea-3/text-to-image"

正是这个字符串让你的集成与模型无关,因此给它命名,并将其视为配置,而不是在每个调用点硬编码。

你不需要预先弄清楚的事

你不需要在首次调用前知道图像尺寸、种子或步数字段的名称。从最小配置开始:认证、模型标识符、提示词。一旦你获得 200 响应,再逐个添加参数,因为一个设置了五个字段的失败请求会给你五个嫌疑对象。一个最小化的失败请求只会给你一个。

用 curl 构建一个可运行的请求

curl 是隔离首次调用两个问题的最快方式:凭证和负载结构。没有 SDK 版本、没有虚拟环境、没有异步运行时——只是线上的一个请求。

最小调用只携带模型真正需要的内容:认证头、模型标识符和提示词。

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-3/text-to-image",
    "prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
  }'

运行前有两点说明。第一,$HIAPI_BASE_URL 是占位符——将其设置为 HiAPI API 参考中的 base URL,并对照同一参考确认路径段。第二,-sS 标志让输出保持安静但仍显示错误,这正是调试时想要的。

健康响应的样子:一个包含生成图像引用或数据以及请求元数据的 JSON 对象。确切结构记录在 API 参考中;不要针对你尚未观察到的结构编写解析代码。将真实响应保存到文件,以便获得基准事实:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
  -o response.json

然后用 jq 或你的编辑器检查它。这个文件就是你的测试夹具:当你移植到 Python 时,对比输出。如果 Python 响应在结构上与 response.json 不同,那么问题在你的代码中,而不是模型中。

先用 curl 做这件事的原因是诊断杠杆。如果 curl 调用成功,你的密钥就是好的,URL 就是对的,模型标识符也能解析——因此之后的任何失败都出在你的应用代码中。如果 curl 调用失败,错误主体会告诉你这三者中哪个出了问题,而你还没写一行代码。

一旦最小请求成功,就一次添加一个参数。每次添加后重新运行 curl。保留成功的请求负载;它们将成为你测试的已接受输入夹具。

Python 中的同一请求

Python 版本刻意保持枯燥:相同的 URL、相同的请求头、相同的 JSON 主体。重点是可移植性——你在 curl 中验证的请求结构应该能迁移到脚本中,再迁移到服务中,而无需重新设计。

import os
import json
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"

def generate(prompt: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"model": MODEL, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate(
        "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
    )
    print(json.dumps(result, indent=2))

几个刻意的选择:

  • 使用环境变量,而非字面量。 密钥绝不出现在源码中。如果变量缺失,os.environ["HIAPI_API_KEY"] 会在启动时大声失败,这比在下面三层出现令人困惑的 401 要好。
  • 在解析前调用 raise_for_status()。 你希望 HTTP 错误以异常形式浮现,而不是当你试图从恰好是 JSON 的错误主体中读取字段时出现 KeyError。
  • 宽松的超时。 图像生成不是即时端点。设置反映这一点的超时,并在生产中显式处理(见生产部分)。
  • 使用 json= 而非手工构建字符串。 让库来序列化。手工拼接 JSON 正是尾随逗号和引号错误的来源。

运行一次,并将输出与之前捕获的 response.json 对比。结构应该匹配。根据响应返回的内容打印图像引用或解码图像数据——同样,针对观察到的结构编写代码,而不是假设的结构。

因为 MODEL 是常量,同一个 generate() 函数适用于平台上的任何图像模型。这就是聚合模型的回报:将其移入服务、添加第二个模型或对输出做 A/B 测试,都只是参数变更,而不是重写。

控制摄影风格与插画风格

风格不是一个开关;它是你推动模型的方向,而 krea-3/text-to-image 响应的是你与摄影师或插画师合作时会用的同样杠杆:主体、媒介、光照和工艺词汇。

向摄影风格推进

摄影输出主要在于命名器械及其后果。描述相机、镜头、胶片和真实光线的词比"逼真"一词更有效。

  • 命名媒介和拍摄方式:"35mm photograph"、"editorial portrait"、"documentary still"。
  • 命名光线:"overcast daylight"、"golden hour backlight"、"single softbox at camera left"。
  • 命名不完美之处:"slight motion blur"、"visible grain"、"shallow depth of field"。

对比 "a fisherman on a dock" 与 "a weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph, visible grain"。第二个提示词将模型约束向摄影的质感和光照,而不是泛泛的描绘。

向插画风格推进

插画在于命名传统、线条品质和调色板——而且通常在于移除你刚刚学到的摄影线索。

  • 命名风格:"flat vector illustration"、"ink and watercolor"、"mid-century editorial illustration"、"isometric line art"。
  • 命名线条:"clean uniform strokes"、"loose gestural linework"。
  • 命名调色板:"restrained two-color palette"、"muted pastels"。

迭代,而非预设

将提示词视为可调配置。一次只改变一个维度——只替换媒介短语,保持主体和光照不变——这样你就能了解每个词元的作用。保留一份提示词变体及其产生输出的简短日志;这份日志比任何预设库都有价值,因为它是针对你的模型和你的内容校准的。

如果请求暴露了提示词之外的参数——尺寸、种子或类似参数——在确定提示词之后再调整它们,而不是之前。同时改变提示词和三个参数,无法告诉你哪个变化起了作用。

排查常见错误

大多数首次调用失败可归入四类。按顺序执行检查清单;每一步都排除一个层面。

认证失败

症状:401 或 403,附带关于凭证或权限的消息。

  • 运行命令的 shell 中真的设置了 HIAPI_API_KEY 吗?echo $HIAPI_API_KEY——空字符串看起来很像错误的密钥。
  • 请求头是否恰好是 Authorization: Bearer <key>?缺少 Bearer、多余的引号或粘贴到密钥中的换行都会导致失败。
  • 密钥是否被吊销,或者是否限定于不同的环境?如有疑问,重新生成并用 curl 调用重新测试。

格式错误的请求负载

症状:400,附带关于主体、字段或 JSON 解析的消息。

  • 发送前验证 JSON。在 curl 中,提示词内一个未转义的引号就会破坏主体。在 Python 中,json= 会为你处理这一点——这是偏好它的另一个原因。
  • 检查是否存在 Content-Type: application/json。
  • 对照 API 参考检查字段名称。拼写正确的值放在错误的字段名下仍然是 400。
  • 退回到最小负载——仅模型和提示词——确认其有效后再逐项添加字段。

错误的模型标识符

症状:404,或 400 提示模型未知或不可用。

  • 逐字符将你的字符串与 krea-3/text-to-image 对比。命名空间前缀、连字符和路径段都很重要。
  • 检查是否因从文档复制粘贴而引入了意外空白或智能引号。
  • 确认该值没有被代码中某处的配置默认值覆盖。

速率和配额响应

症状:429,或关于限制或余额不足的消息。

  • 退避并在短暂延迟后重试,而不是猛击端点。
  • 在仪表盘中检查你的用量和余额。
  • 如果这发生在开发期间,查找一个触发速度比你想象更快的重试循环——try 块内一个失败请求加上激进的重试会迅速耗尽限制。

如果以上都没有解决,从响应中捕获完整的请求 ID 和错误主体并发送给支持。聚合 API 上的错误主体通常足够具体,能指明问题;错误在于转述它们而不是粘贴它们。

投入生产

你现在的请求是原型。四项实践能将其变成可以持续运行的东西。

按类别处理错误,而非按字符串

将 HTTP 状态码映射到行为:认证错误是配置缺陷,应呼叫某人;4xx 负载错误是代码缺陷,应让请求大声失败;429 和 5xx 是瞬态的,应以指数退避和抖动重试。永远不要重试 400——你只会浪费配额去确认同一个缺陷。设置显式超时,并将超时视为瞬态。

if response.status_code == 429 or response.status_code >= 500:
    raise TransientError(response.status_code)
response.raise_for_status()

记录提示词,并版本化

每张生成的图像都应能追溯到产生它的确切提示词。将提示词、模型标识符、参数和响应请求 ID 一起存储。将提示词文本视为版本化配置——一个签入配置文件的 prompt_v3 字符串,而不是埋在函数中的字面量。当输出质量发生变化时,你需要知道是提示词、参数还是模型改变了。

将模型名称保留在配置中

krea-3/text-to-image 应只出现一次,在常量或配置条目中。这正是聚合模型的回报:替换模型、运行对比或回滚都变成配置变更,而不是部署新的代码路径。它也使得日后将不同工作负载路由到不同模型变得轻而易举。

针对夹具测试

将本教程中捕获的成功响应保存为夹具。断言你的解析代码能处理它们,并使用记录的错误主体来测试错误映射。你将在用户之前发现响应结构漂移。

从最小的 curl 调用开始,确认响应结构,原样移植到 Python,然后一次一个维度地迭代提示词——并查阅 HiAPI API 参考以获取可能变化的端点细节。

立即开始构建持久 AI 产物

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

阅读 API 文档