---

slug: flux-2-klein-4b-text-to-image-api-guide locale: en title: Как использовать flux-2-klein-4b/text-to-image через hiapi API category: tutorial summary:

• Простейшие примеры на curl и Python для вызова flux-2-klein-4b/text-to-image через единый эндпоинт hiapi /v1/tasks.
• 'Полная таблица параметров: prompt, значения перечисления aspect_ratio и seed — строгая схема отклоняет неизвестные поля.'
• 'Заметки для продакшена: выбор между 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: Руководство по API генерации изображений flux-2-klein-4b meta_description: 'Вызов flux-2-klein-4b/text-to-image на curl и Python: создание задачи, опрос для получения изображения и обработка колбэков, идемпотентности и ошибок в продакшене.' keywords:
• flux-2-klein-4b text-to-image api
• пример api flux-2-klein-4b
• api генерации изображений hiapi
• 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

---

Как использовать flux-2-klein-4b/text-to-image через hiapi API

Что вы построите

Скрипт, который отправляет подсказку в flux-2-klein-4b/text-to-image, ждёт генерации изображения, а затем скачивает его — плюс детали для продакшена, о которых нужно знать перед запуском без присмотра (колбэки, идемпотентность, структуры ошибок).

Предварительные требования: получите API key в консоли hiapi. Каждый запрос ниже аутентифицируется с помощью 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 использует строгую схему входных данных — отправка полей, которые она не знает (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"}
}

Идемпотентность. Задайте заголовок Idempotency-Key в вызове POST /v1/tasks (до 255 байт). Повторная попытка с тем же запросом и тем же ключом в рамках одной учётной записи не создаст вторую задачу — вы получите исходный 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 со своей собственной схемой входных данных.

В чём разница между flux-2-klein-4b и flux-2-klein-9b? Оба — эндпоинты генерации изображений из текста в одной серии FLUX.2 [klein]; 9b — более крупная из двух. Перед переключением посмотрите страницу модели 9b, чтобы узнать её актуальную цену и параметры.

Можно ли запросить несколько изображений за один вызов? Нет — схема не принимает n или поля количества. Для каждого изображения нужно отправить отдельный запрос.

Сколько действует возвращённый URL изображения? output[0].url — это временная ссылка со своей меткой времени expireAt; считайте её краткосрочной (в тестах около недели) и скачивайте байты изображения сразу после успешного завершения задачи, а не сохраняйте URL.

Почему я получаю ошибку 401 permission_denied? Ваш ключ отсутствует, недействителен или не имеет доступа к этой модели. Убедитесь, что вы отправляете Authorization: Bearer sk-... и используете ключ из консоли, а не заполнитель.

Нужно ли запускать собственный сервер для использования этого API? Только если вам нужны колбэки. Опрос GET /v1/tasks/{taskId} из скрипта, задачи cron или бессерверной функции вполне работает при низком трафике; когда объём генераций вырастет, переключитесь на callback.url.