---

slug: flux-2-klein-9b-text-to-image-api-guide locale: en title: 如何通过 hiapi API 使用 flux-2-klein-9b/text-to-image category: tutorial summary:

• 通过 hiapi 统一的 /v1/tasks 端点调用 flux-2-klein-9b/text-to-image 的最小 curl 和 Python 示例。
• '完整参数表：prompt、aspect_ratio、num_inference_steps、output_format 和 seed——严格的 schema 会拒绝未知字段。'
• '生产注意事项：callback.url 与轮询的对比、Idempotency-Key 请求头，以及两种错误响应结构。 takeaways:
• 用 POST /v1/tasks 创建任务，然后轮询 GET /v1/tasks/{taskId} 或使用 callback.url 获取结果。
• num_inference_steps 只接受 4-8（整数）；此模型没有 size 或 n 字段。
• 重试时使用相同的 Idempotency-Key 请求头会返回相同的 taskId——在超时时可安全复用。
• 400 错误使用 error_code，401 认证错误使用嵌套的 error.code——请先检查 HTTP 状态码。 meta_title: flux-2-klein-9b 文本生图 API 指南 meta_description: 使用 curl 和 Python 调用 flux-2-klein-9b/text-to-image；创建任务、轮询图像，并在生产环境中处理回调、幂等性和错误。 keywords:
• flux-2-klein-9b 文本生图 api
• flux-2-klein-9b api 示例
• hiapi 图像生成 api
• flux klein api curl python tags:
• api-guide
• image-generation
• flux author_name: hiapi is_published: false cover_image: https://static.hiapi.ai/blog/_default/recipe-cover.jpg

---

如何通过 hiapi API 使用 flux-2-klein-9b/text-to-image

你将构建什么

一个脚本，它将提示词发送给 flux-2-klein-9b/text-to-image，等待图像生成完成并下载它——此外还包括在无人值守运行之前所需的生产细节（回调、幂等性、错误结构）。

前提条件：从 hiapi 控制台获取 API 密钥。下面的每个请求都使用 Authorization: Bearer sk-<your-api-key> 进行认证。

最小可运行示例

hiapi 的生成模型运行在一个统一的异步端点之后：POST /v1/tasks 会创建一个任务并立即返回一个 taskId；然后你轮询 GET /v1/tasks/{taskId} 直到它达到终态。

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

返回结果：

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

轮询同一个任务，直到 data.status 从 handling 变为 success（中间会短暂经过 archiving）：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01K... \
  -H "Authorization: Bearer sk-<your-api-key>"

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../01K...-0.png", "expireAt": 1785941465}
    ]
  },
  "message": "success"
}

data.output[0].url 就是生成的图像。它是一个临时链接——在测试中，生成后约 7 天过期——因此请下载字节并自行存储，而不是直接链接到它。

Python 中的相同流程（含轮询）

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE = "https://api.hiapi.ai/v1"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
        "prompt": "a red fox walking through fresh snow, golden hour light",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "failed":
        raise RuntimeError(f"generation failed: {task}")
    time.sleep(3)

image_bytes = requests.get(image_url).content
open("fox.png", "wb").write(image_bytes)

重要参数

flux-2-klein-9b/text-to-image 具有严格的输入 schema——发送它不认识的字段（size、n、negative_prompt，或其他 hiapi 图像模型接受的任何字段）都会被直接拒绝，因此不要在不先查看模型页面的情况下跨模型复制参数。

字段	是否必填	说明
prompt	是	描述图像的字符串。
aspect_ratio	否	1:1、4:3、3:4、16:9、9:16 之一。省略时默认为 4:3。
num_inference_steps	否	整数，4–8。默认为 4；更高的值以速度换取稍多的细节。
output_format	否	jpeg、png、webp 之一。默认为 png。
seed	否	整数。复用 seed 可使多次调用的结果可复现。

完整参数参考见模型页面；当前按图像计费的价格见定价页面——请在那里查看，而不要硬编码数字，因为基于用量的费率会变化。

生产环境说明

用回调替代轮询。 对于快速脚本以外的任何场景，跳过轮询循环，在任务创建请求体中添加 callback.url（以及 "when": "final"）——hiapi 会在任务完成后将结果 POST 到你的端点，其负载结构与 GET /v1/tasks/{taskId} 返回的完全一致。有关回调字段和签名验证的详细信息，请参阅创建任务。

{
  "model": "flux-2-klein-9b/text-to-image",
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"},
  "input": {"prompt": "a red fox walking through fresh snow, golden hour light"}
}

幂等性。 在 POST /v1/tasks 调用上设置 Idempotency-Key 请求头（最多 255 字节）。在同一账户下使用相同密钥重试同一请求不会创建第二个任务——你会拿回原始的 taskId。这正是它能够安全重试在你这边超时的请求而不会重复计费的原因。

错误处理。 实践中会出现两种不同的失败结构，因此要检查两者：

• 错误的 input（缺少 prompt、num_inference_steps 超出范围、不支持的字段）会返回 HTTP 400 和 {"error_code": "INVALID_REQUEST", "message": "..."}。
• 无效或未授权的 API 密钥会返回 HTTP 401，并带有不同的响应结构：{"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}。

首先根据 HTTP 状态码分支处理，然后读取实际存在的错误字段——不要假设所有失败都使用同一种响应结构。

相关资源

• 获取任务详情——完整轮询参考
• 认证——API 密钥作用域和请求头格式
• flux-2-klein-9b/image-to-image——同一系列，对输入图像进行编辑而非从头生成
• flux-2-klein-4b/text-to-image——同一 klein 系列中更小、更快的模型

常见问题

flux-2-klein-9b/text-to-image 支持图生图吗？ 不直接支持——那是一个单独的模型 flux-2-klein-9b/image-to-image，拥有自己的输入 schema。

flux-2-klein-9b 和 flux-2-klein-4b 有什么区别？ 两者都是同一 FLUX.2 [klein] 系列中的文本生图端点；9b 是两者中较大的一个，旨在实现更强的真实感、文本渲染和细节。切换前请查看 4b 模型页面以了解其当前定价和参数。

可以在一次调用中请求多张图像吗？ 不能——schema 不接受 n 或计数类字段。每张图像请发送一个请求。

返回的图像 URL 有效期多长？ output[0].url 是一个临时链接，带有自己的 expireAt 时间戳；请将其视为短时效（测试中大约一周），并在任务成功后立即下载字节，而不是存储 URL。

为什么我收到 401 permission_denied 错误？ 你的密钥缺失、无效，或无权访问此模型。确认你发送的是 Authorization: Bearer sk-... 以及来自控制台的密钥，而不是占位符。

使用此 API 需要运行自己的服务器吗？ 只有在你需要回调时才需要。从脚本、定时任务或无服务器函数轮询 GET /v1/tasks/{taskId} 对于低用量使用完全没问题；当生成规模扩大后，切换到 callback.url。