教程
如何通过 HiAPI API 使用 krea-3/text-to-image:curl、Python 与一个可运行的请求
本页内容
为什么通过聚合 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 参考以获取可能变化的端点细节。