flux-2-klein-9b API: руководство по curl и Python

Сгенерировать изображение с помощью flux-2-klein-9b на hiapi можно одним вызовом POST /v1/tasks плюс опрос — в точности как в асинхронной схеме задач, используемой каждым моделью на платформе. Это руководство фиксирует реальный запрос и ответ (создание задачи, опрос и итоговый URL изображения), поэтому приведённый ниже код можно скопировать и запустить, а не просто ознакомиться с ним.

Что вам понадобится

1. API-ключ hiapi — создайте его в консоли. Он отправляется с каждым запросом как Bearer token.
2. Полный ID модели, включая суффикс эндпоинта. flux-2-klein-9b доступна только через flux-2-klein-9b/text-to-image — указание только flux-2-klein-9b вернёт 400 (см. ниже).

Минимальный рабочий запрос (curl)

Создание задачи:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a weathered lighthouse on a rocky coast at sunset, cinematic lighting",
      "aspect_ratio": "16:9"
    }
  }'

Ответ:

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

Опрос задачи до завершения:

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

Ответ при завершении:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM",
    "status": "success",
    "model": "flux-2-klein-9b/text-to-image",
    "created": 1787581018,
    "completed": 1787581030,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T23CG2GNPENYQV4WEKZJTM-0.png",
        "artifactId": "96193",
        "expireAt": 1788185830
      }
    ]
  },
  "message": "success"
}

output[0].url — это и есть тот PNG. В тесте задача от отправки до success заняла около 12 секунд. Обратите внимание на expireAt — перед тем как строить какие-либо функции, зависящие от постоянной доступности этого URL, прочитайте примечания о хранении ниже.

Тот же процесс на Python

import time
import requests

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


def create_image(prompt: str, aspect_ratio: str = "1:1") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "flux-2-klein-9b/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio},
        },
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_image(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image("a weathered lighthouse on a rocky coast at sunset, cinematic lighting", "16:9")
    image_url = wait_for_image(task_id)
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print(f"saved output.png from task {task_id}")

Параметры, которые flux-2-klein-9b действительно проверяет

Схема входных данных очень строгая — если отправить любое поле, не указанное в списке, API отклонит весь запрос ещё до постановки в очередь:

• prompt (строка, обязательный) — единственное обязательное поле.
• aspect_ratio (строка, необязательный) — одно из значений 1:1, 4:3, 3:4, 16:9, 9:16. Любое другое значение вернёт 400 с сообщением value must be one of ....
• seed (целое число, необязательный) — при одинаковом prompt с одинаковым seed результат воспроизводим.
• output_format (строка, необязательный) — одно из значений jpeg, png, webp.

Это вся схема. Полей size, quality, strength или n нет — отправка любого из них приведёт к ошибке:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'size' not allowed"}

flux-2-klein-9b поддерживает только генерацию изображений из текста. Она также не принимает image_urls — для редактирования изображения используйте отдельный ID модели flux-2-klein-9b/image-to-image, который принимает другую структуру входных данных.

ID модели должен содержать суффикс эндпоинта

Некоторые модели на hiapi разрешаются по голому ID (например, gpt-image-2), но flux-2-klein-9b к ним не относится. Без суффикса задача никогда не будет создана:

{"code":400,"data":null,"error_code":"MODEL_UNAVAILABLE","message":"model not available via /v1/tasks"}

Всегда отправляйте полную строку flux-2-klein-9b/text-to-image в поле model.

Замечания для продакшена

• Две разные структуры ошибок. Ошибки валидации (отсутствующее поле, неверное значение перечисления, неизвестный ключ) возвращаются в виде верхнеуровневого {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Ошибки аутентификации/прав возвращаются как {"error":{"code":"permission_denied","message":"...","request_id":"..."}} — вложенный объект error, HTTP 401. В обработке ошибок проверяйте обе структуры; код, который проверяет только resp["code"], пропустит случаи с 401.
• permission_denied относится к ключу, а не к запросу. Если prompt присутствует и имеет правильный тип, но вы всё равно получаете 401 permission_denied, значит у самого API-ключа не включена эта модель — проверьте это в консоли, а не ваш JSON.
• Хранилище результатов временное. storage: "temp", и каждый результат содержит Unix-метку expireAt — в зафиксированном примере примерно через неделю после создания. Сразу после успешного завершения задачи скачивайте файл или перекладывайте его в собственное хранилище; не сохраняйте URL temp.hiapi.ai как постоянный адрес.
• Для пакетных задач используйте callback. Опрашивать одну картинку нормально; опрашивать пятьдесят — это пятьдесят повторных запросов. Укажите на верхнем уровне запроса создания callback: {"url": "...", "when": "final"}, чтобы hiapi один раз отправил вам результат, когда задача действительно завершится. Сейчас when поддерживает только одно значение — "final".
• Повторяйте попытку до получения taskId, а не после. При сетевой ошибке или 5xx на первоначальном POST /v1/tasks повторять безопасно — в этот момент ещё ничего не создано. Как только вы получили taskId, повторная отправка того же prompt создаст второе, не связанное с первым изображение; в этом случае вместо этого опрашивайте задачу или ждите callback.

Связанные материалы

• Страница модели flux-2-klein-9b — актуальные цены и онлайн-демо.
• Справочник по flux-2-klein-9b — справочная запись, посвящённая этой модели.
• Цены hiapi — тарифы моделей в каталоге.
• Документация по API асинхронных задач — полная схема создания/опроса, общая для всех моделей hiapi.

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

Почему при вызове flux-2-klein-9b возвращается MODEL_UNAVAILABLE? ID модели требует суффикса эндпоинта. Используйте flux-2-klein-9b/text-to-image, а не голый flux-2-klein-9b.

Какие соотношения сторон поддерживает flux-2-klein-9b? Пять: 1:1, 4:3, 3:4, 16:9, 9:16. Любое другое значение вернёт 400 с сообщением value must be one of, перечисляющим эти пять значений.

Можно ли управлять качеством или разрешением результата? Нет — схема принимает только prompt, aspect_ratio, seed и output_format. Параметров size или quality нет; отправка любого из них вернёт 400 с ошибкой additional properties.

Можно ли редактировать изображения с помощью flux-2-klein-9b? Нет, через этот ID модели. Используйте flux-2-klein-9b/image-to-image — у него собственная независимая схема входных данных.

Сколько действует URL результата? storage имеет значение "temp", и каждый результат содержит Unix-метку expireAt, фактически примерно через неделю. Сразу после успешного завершения задачи скачайте или загрузите файл заново — не используйте URL как постоянный адрес.

Почему ключ, работающий с другими моделями, возвращает 401 на этой модели? Доступ к моделям выдаётся по ключам. Ответ 401 с error_code: "permission_denied" означает, что у данного конкретного ключа нет разрешения на flux-2-klein-9b — включите его в консоли, это не ошибка в теле вашего запроса.