Как пользоваться API генерации изображений по тексту на FLUX.2? Параметры, код и одно реальное сгенерированное изображение

TL;DR

• Имя модели FLUX.2 Pro для генерации изображений по тексту в HiAPI — flux-2/text-to-image, от Black Forest Labs; сильные стороны — следование промпту и текст внутри изображения. Откройте страницу модели и попробуйте прямо в браузере.
• Оплата по уровням разрешения: 0.5 MP — $0.0375, 1 MP (по умолчанию) — $0.05, 2 MP — $0.075, 4 MP — $0.125. Соотношение сторон на цену не влияет.
• Самый быстрый способ вызова: POST /v1/tasks с prompt, опрашивать до статуса success, скачать output[0].url. В значении resolution есть пробел, писать нужно "1 MP".

Сначала посмотрим на реальное изображение

Это изображение сгенерировано запросом из статьи: 2 MP, 16:9:

A wide overhead flat-lay of a modern developer desk: a matte black mechanical
keyboard on the left, a ceramic mug of steaming coffee on the right, a small
potted succulent in the top corner, and an open spiral notebook in the center
with the handwritten words 'API ready' clearly visible on the page, soft
natural window light falling from the left, a muted teal and warm wood color
palette, no other text or logos anywhere in the frame

Сгенерировать этим промптом → (16:9, 2 MP)

flux-2/text-to-image, 16:9, 2 MP, $0.075. Надпись «API ready» на ноутбуке написана правильно, лишнего текста в кадре нет.

Шпаргалка по параметрам

Поле	Обязательно	Значения	Описание
prompt	Да	Строка	Важные элементы — в начале предложения, лучше всего работает 30–80 английских слов
aspect_ratio	Нет	1:1 16:9 3:2 2:3 4:5 5:4 9:16 3:4 4:3 custom, по умолчанию 1:1	При выборе custom используется вместе с width / height
resolution	Нет	0.5 MP / 1 MP / 2 MP / 4 MP, по умолчанию 1 MP	Определяет цену; при custom игнорируется
width / height	Только для custom	256–2048	Автоматически округляется до кратного 16
output_format	Нет	webp (по умолчанию) / jpg / png
output_quality	Нет	0–100, по умолчанию 80	Действует только для webp, jpg
seed	Нет	Целое число	При фиксации позволяет воспроизвести тот же результат
safety_tolerance	Нет	1–5, по умолчанию 2	1 — самый строгий

Параметры проверяются строго: если передать лишнее поле, которого нет в документации, сразу вернётся HTTP 400 (additional properties ... not allowed). Этот эндпоинт принимает только текст; чтобы редактировать изображение по референсу, используйте flux-2/image-to-image.

curl: получаем первое изображение

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A matte charcoal coffee bag on a rustic oak counter, kraft paper label reading DAYBREAK ROAST, warm morning window light",
      "aspect_ratio": "4:3",
      "resolution": "1 MP",
      "output_format": "png"
    }
  }'

В ответе будет только data.taskId, изображение ещё не сгенерировано. Опрашивайте GET /v1/tasks/{taskId}, после того как status станет success, скачивайте из output[0].url.

Python: отправка, опрос, скачивание

# pip install requests; export HIAPI_KEY=ваш Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=300, **inp):
    # при повторной отправке того же запроса используйте тот же Idempotency-Key — списание будет только одно
    r = requests.post(API, json={"model": "flux-2/text-to-image", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

url = generate(
    prompt="A wide overhead flat-lay of a modern developer desk, an open notebook with the handwritten words 'API ready', soft window light",
    aspect_ratio="16:9", resolution="2 MP", output_format="png", seed=42,
)
with open("desk.png", "wb") as f:
    f.write(requests.get(url).content)

Сколько стоит

Разрешение	За изображение	За 100 изображений
0.5 MP	$0.0375	$3.75
1 MP (по умолчанию)	$0.05	$5.00
2 MP	$0.075	$7.50
4 MP	$0.125	$12.50

Текущие цены HiAPI, проверено 18 октября 2026 г.

Соотношение сторон, seed и формат вывода на цену не влияют — только уровень разрешения. За неудачные генерации плата не списывается. Если нужно дешевле, FLUX.2 [klein] 4B 1 MP стоит $0.00143 за изображение, сравнение всех уровней см. в Цены FLUX.2 API.

Перед запуском в продакшн

• В resolution есть пробел: пишите "1 MP", а не "1MP" или "1K"; при ошибке вернётся 400 со списком допустимых значений.
• При размере custom resolution игнорируется: если в aspect_ratio указано custom, изображение генерируется по width × height.
• Для воспроизводимости фиксируйте seed: при одинаковом промпте и одинаковом seed результаты очень близки, что удобно для сравнения при правке формулировок.
• Сразу сохраняйте результат: у output[0].url есть срок действия, после скачивания сохраните в своё хранилище.
• Используйте callback вместо опроса: на уровне input добавьте "callback": {"url": "https://your-app.example.com/hiapi/callback"} и дедуплицируйте по taskId.

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

Обязательно ли указывать resolution?

Не обязательно, по умолчанию 1 MP. Но лучше указывать каждый раз, чтобы не перепутать с 4 MP.

Можно ли передать референсное изображение?

В этот эндпоинт нельзя. Для редактирования по референсу и композитинга нескольких изображений используйте flux-2/image-to-image, до 8 референсных изображений; готовые промпты см. в Промпты для редактирования FLUX.2.

Почему возвращается «additional properties not allowed»?

Передано поле, которого нет у этой модели, например strength, prompt_upsampling. Используйте только поля из таблицы параметров выше.

Как выбрать между FLUX.3 Image и этой моделью?

FLUX.3 Image — одно имя модели одновременно генерирует и редактирует изображения, умеет 4K, до 10 референсных изображений; у FLUX.2 Pro есть seed и произвольные ширина/высота, а 4 MP стоит всего $0.125. Сравнение на одинаковых промптах см. в FLUX.3 Image vs FLUX.2.

Скопируйте промпт про рабочий стол выше и сгенерируйте первое изображение на странице модели.