Как использовать Recraft V4.1 API? За 5 минут запустите генерацию с фирменной палитрой

TL;DR

• Серия Recraft V4.1 — это пара моделей text-to-image с полностью идентичными параметрами: recraft-v4.1/text-to-image выдаёт более детализированный финальный вариант ($0.05/шт.), recraft-v4.1-flash/text-to-image — быстрые черновики ($0.01/шт., полные цены см. на странице цен), отличие только в поле model. Откройте страницу модели, чтобы попробовать; новым пользователям при регистрации дают 200 кредитов.
• Особенность — фирменная палитра: в colors передаётся набор RGB, и изображение по возможности выдерживается в этих цветах (в Playground пока недоступно, только через API).
• Вызов идёт через эндпоинт HiAPI /v1/tasks: отправьте задачу и получите taskId, затем запросите результат и после успеха скачайте по output[0].url.

Что она умеет

• Фотография, иллюстрация, постер — всё сразу: реалистичные изображения продуктов, плоские векторные иллюстрации, постеры с заголовком — одним описанием.
• Управляемая палитра: colors задаёт палитру, background_color — цвет фона; при создании фирменных материалов выдерживается VI.
• 6 пресетов размера: square_hd (по умолчанию), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9; произвольные ширина и высота не поддерживаются.
• Flash для черновиков + V4.1 для финала: параметры одинаковые, меняется только model; 10 черновиков плюс 1 финальный вариант — $0.15.

Ниже — реальный результат V4.1:

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

(По-китайски это значит: минималистичный постер бренда кофе специальной обжарки, огромный жирный заголовок без засечек "NORTH BEAN", тёплая палитра терракоты и кремового, иллюстрация одного кофейного зерна, много свободного пространства, швейцарская модульная сетка. Размер — portrait_4_3.)

recraft-v4.1/text-to-image, portrait_4_3, пример изображения из этой статьи 896×1216, $0.05.

Сгенерировать с этим промптом →

Как выбрать между двумя моделями

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
За штуку	$0.01	$0.05
Назначение	Быстрые черновики, выбор направления	Более детализированный финальный вариант
Параметры	Полностью идентичны (prompt / image_size / colors / background_color)	То же
Подходит для	Массового поиска, иллюстраций для соцсетей, раундов черновиков	Финальных материалов, фирменных материалов

Обе модели работают в одном конвейере: Flash выдаёт 10 направлений за $0.10, выбранное направление перезапускается с другим model как финал V4.1 за $0.05 — весь набор $0.15. Если нужны только наброски, весь процесс на Flash: 1 000 штук обойдутся всего в $10.00. Промпты под разные сценарии смотрите в сборнике промптов.

Два пути к старту

3 шага в браузере: откройте страницу модели → вставьте промпт, выберите размер → нажмите «Сгенерировать», один вариант V4.1 стоит $0.05. (colors и background_color доступны только через API.) В первый раз советуем сначала запустить один вариант в браузере, убедиться, что стиль соответствует ожиданиям, и только потом писать код.

3 шага через API: POST /v1/tasks для отправки → получите taskId → GET /v1/tasks/<taskId> до статуса success, затем скачайте.

curl: первый вариант (с фирменной палитрой)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

Здесь используются реальные параметры примера Flash: палитра из трёх цветов — тёмно-синего, оранжевого и пшеничного — плюс кремовый фон. Для финального варианта замените model на recraft-v4.1/text-to-image, остальное не трогайте.

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

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Таблица параметров (одинаковая для обеих моделей)

Поле	Обязательное	Значения	Описание
prompt	Да	1–10000 символов	Описание изображения
image_size	Нет	square_hd (по умолчанию) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6 пресетов, произвольные ширина и высота не поддерживаются
colors	Нет	Массив RGB-объектов, каждый канал 0–255	Сильное управление палитрой: изображение по возможности выдерживается в этих цветах; в Playground пока недоступно
background_color	Нет	Один RGB-объект	Цвет фона; в Playground пока недоступно

В каждом RGB-объекте все три ключа r/g/b обязательны, каждый 0–255, лишние ключи не допускаются. Если в теле запроса есть поле вне таблицы, сразу возвращается 400.

Ошибки, которые вы встретите (исходный текст интерфейса)

Что вы сделали	Ответ
Не передали prompt	400 invalid input: prompt: missing required field "prompt"
Передали в image_size объект с шириной и высотой	400 invalid input: image_size: got object, want string
Передали в канал colors значение 256	400 invalid input: colors.0.r: maximum: got 256, want 255
В colors не хватает ключа b	400 invalid input: colors.0.b: missing required field "b"
Передали colors как строку	400 invalid input: colors: got string, want array
Передали в RGB-объект лишний ключ	400 invalid input: colors.0: additional properties 'a' not allowed
Недостаточно средств	402 insufficient account balance; top up and retry
Повторная отправка с тем же Idempotency-Key возвращает 409 или 422 — попробуйте с новым ключом.

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

• Callback: на верхнем уровне тела запроса передайте "callback": {"url": "https://..."}, и о конечном статусе придёт уведомление автоматически.
• Скачивайте вовремя: output[0].url — временный адрес; скачайте и сохраните в своё хранилище сразу после получения, не используйте его как постоянную ссылку.
• Палитра — это ориентир, а не блокировка: если в промпте указаны цвета, конфликтующие с colors, результат может смешать оба варианта; для строгого соблюдения цветов не пишите другие цвета в промпте.
• Flash→V4.1 — только смена model: остальные параметры сохраняются как есть, идея композиции используется напрямую.

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

У двух моделей одинаковые параметры?

Полностью одинаковые. Меняется только поле model, код не требует изменений.

Где задаются параметры colors?

Только через API. В Playground параметры colors и background_color пока недоступны.

Гарантирует ли colors использование только указанных цветов?

Нет. Это сильный ориентир: изображение по возможности выдерживается в этих цветах, но жёсткой блокировки нет.

Сколько изображений за раз?

По одному за раз. Для нескольких отправляйте несколько задач или ставьте их в очередь.

Сколько изображений можно получить за $10?

Flash стоит $0.01 за штуку, за $10 — 1 000 изображений. За неудачные попытки деньги не списываются.

Далее: возьмите промпт NORTH BEAN и сгенерируйте один вариант на странице модели; если нужно выдержать фирменные цвета, добавьте colors в запрос API; шаблоны под сценарии смотрите в сборнике промптов.