---

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

• 通过 hiapi 统一的 /v1/tasks 端点调用 flux-2-klein-4b/text-to-image 的最简 curl 和 Python 示例。
• '完整参数表：prompt、aspect_ratio 枚举值和 seed —— 严格的 schema 会拒绝未知字段。'
• '生产环境注意事项：callback.url 与轮询的取舍、Idempotency-Key 请求头，以及两种错误响应包结构。' takeaways:
• 用 POST /v1/tasks 创建任务，然后轮询 GET /v1/tasks/{taskId}，或使用 callback.url 接收结果。
• aspect_ratio 支持 11 种命名比例；该模型没有 size 或 n 字段。
• 重试时携带相同的 Idempotency-Key 请求头会返回相同的 taskId —— 在超时时可安全复用。
• 400 错误使用 error_code，401 鉴权错误使用嵌套的 error.code —— 请先检查 HTTP 状态码。 meta_title: flux-2-klein-4b 文生图 API 指南 meta_description: '使用 curl 和 Python 调用 flux-2-klein-4b/text-to-image：创建任务、轮询获取图片，并在生产环境中处理回调、幂等性和错误。' keywords:
• flux-2-klein-4b 文生图 api
• flux-2-klein-4b api 示例
• hiapi 图像生成 api
• flux 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-4b/text-to-image

你将构建什么

一个脚本：向 flux-2-klein-4b/text-to-image 发送提示词，等待图片生成，然后下载图片 —— 此外还包括在无人值守运行前需要了解的生产环境细节（回调、幂等性、错误结构）。

前提条件：从 hiapi 控制台获取一个 API key。下面的每个请求都使用 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-4b/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.jpg", "expireAt": 1785939579}
    ]
  },
  "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-4b/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.jpg", "wb").write(image_bytes)

重要参数

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

字段	必填	说明
prompt	是	描述图片的字符串。
aspect_ratio	否	可选值之一：1:1、16:9、9:16、3:2、2:3、4:3、3:4、5:4、4:5、21:9、9:21。省略时默认为 1:1。
seed	否	整数。复用同一个 seed 可使多次调用结果可复现。

完整参数参考见模型页面；当前每张图片的价格见定价页面 —— 请以那里为准，而不是硬编码数字，因为按用量计费的价格会变动。

生产环境说明

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

{
  "model": "flux-2-klein-4b/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 字节）。在同一账户下使用相同 key 重试相同请求不会创建第二个任务 —— 你会拿回原始的 taskId。正因如此，才能安全地重试在你这边超时的请求，而不会重复计费。

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

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

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

相关资源

• 获取任务详情 —— 完整的轮询参考
• 鉴权 —— API key 的作用域和请求头格式
• flux-2-klein-4b/image-to-image —— 同一系列，对输入图片进行编辑而非从零生成
• flux-2-klein-9b/text-to-image —— 同属 klein 系列的更大模型

常见问题

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

flux-2-klein-4b 和 flux-2-klein-9b 有什么区别？ 两者都是同一 FLUX.2 [klein] 系列中的文生图端点；9b 是两者中更大的那个。切换前请查看 9b 模型页面了解其当前价格和参数。

可以在一次调用中请求多张图片吗？ 不可以 —— schema 不接受 n 或数量字段。每张图片需要发送一次请求。

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

为什么我收到 401 permission_denied 错误？ 你的 key 缺失、无效，或没有访问该模型的权限。确认你发送的是 Authorization: Bearer sk-...，且使用的是来自控制台的 key，而不是占位符。

使用此 API 需要运行自己的服务器吗？ 只有当你需要回调时才需要。从脚本、cron 任务或无服务器函数中轮询 GET /v1/tasks/{taskId} 在低流量场景下完全可行；当生成规模变大时，再切换到 callback.url。