Как использовать API преобразования текста в изображение krea-2-medium-turbo (curl + Python)

krea-2-medium-turbo — это быстрый и недорогой тариф преобразования текста в изображение, который Krea предоставляет на hiapi. Достаточно отправить один промпт и выбрать соотношение сторон, чтобы через асинхронный API задач получить готовое изображение. В этом руководстве приведены готовые к копированию примеры запросов на curl и Python для /v1/tasks, точная схема входных данных, а также измеренные мной 2026-10-21 задержки и поведение при ошибках — причём один результат противоречит описанию в документации.

Предварительные требования

API-ключ hiapi (sk-...). Создайте его в консоли API Keys. Каждый запрос аутентифицируется через Authorization: Bearer sk-<your-key>. Это единственное требование — модель работает на стороне сервера, поэтому кроме HTTP-клиента ничего устанавливать не нужно.

Схема входных данных

krea-2-medium-turbo принимает пять полей. Обязательны только prompt и model:

Поле	Обязательно	Тип	По умолчанию	Описание
model	Да	string	—	Должно быть ровно krea-2-medium-turbo.
prompt	Да	string	—	1–5000 символов.
aspect_ratio	Нет	enum	1:1	Одно из: 1:1, 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3, 9:16.
creativity	Нет	enum	low	raw (максимально буквально) → low → medium → high (максимально творчески).
seed	Нет	integer	—	Необязательно. Прежде чем полагаться на него, прочитайте замечание о seed ниже.

Объект input является строгим (additionalProperties: false): любое поле, отсутствующее в этой таблице, будет отклонено до начала генерации. Здесь нет n / num_images, нет resolution или size, а также нет поля негативного промпта. Один запрос возвращает ровно одно изображение, а размер вывода полностью определяется aspect_ratio. Если вы использовали другие API изображений на hiapi, принимающие resolution (Seedream, Qwen-Image) или size, уберите эти поля здесь — они вернут 400.

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

Создание задачи сразу возвращает taskId; изображение рендерится в фоне.

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

Ответ:

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

Затем опрашивайте задачу по id, пока она не достигнет терминального состояния:

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

Завершённая задача выглядит так (поля сокращены для наглядности):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

Изображение находится в data.output[0].url.

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

import time
import requests

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

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # Опрашивайте, пока задача не достигнет терминального состояния.
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # Внимание: всё ещё HTTP 200, см. ниже
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

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

• Опрос или колбэки. Цикл выше опрашивает каждые 3 секунды, что нормально для низкой нагрузки. В продакшене можно при создании запроса указать callback.url и задать when: "final", чтобы hiapi POST-ил завершённую задачу вам вместо опроса — соглашение о колбэках см. в документации task API.
• Сбой генерации всё равно возвращает HTTP 200. HTTP-код на эндпоинте опроса показывает, успешен ли запрос, а не изображение. Ошибка рендеринга возвращается как 200 с data.status: "fail". Ветвитесь по data.status, а не по HTTP-коду, иначе вы примете сбой за успех.
• URL вывода временные. Результаты хранятся под "storage": "temp" на temp.hiapi.ai с меткой времени expireAt и истекают примерно через семь дней (в моём запуске — 604 800 секунд). Скачивайте байты сразу по завершении задачи и переразмещайте их (в своём bucket/CDN) — не используйте прямые ссылки на URL temp.hiapi.ai на продакшен-страницах.
• Цена — единый фиксированный тариф за изображение, независимо от соотношения сторон или уровня креативности — никаких градаций по разрешению. Сверяйтесь с текущими цифрами на странице цен, а не хардкодьте их.

Что я реально протестировал (2026-10-21)

Всё ниже получено из живых вызовов, а не из документации:

• Задержка и разрешение. Запрос с 2.35:1 завершился примерно за 26 секунд (разница created → completed), возвращённый PNG — 1568 × 672 px, то есть 2.35:1 действительно даёт широкоэкранную кинематографическую обрезку, а не почти квадрат. Во время рендеринга и перемещения файла во временное хранилище задача проходит промежуточные состояния handling → archiving → success.
• Проверка enum выполняется на сервере. Отправка "aspect_ratio": "21:9" (правдоподобное, но неподдерживаемое значение) немедленно возвращает 400: invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'. Сообщение об ошибке указывает поле и перечисляет допустимые значения, что удобно для программной обработки.
• Неизвестные поля возвращают 400 и не игнорируются. "resolution": "2K" возвращает invalid input: <root>: additional properties 'resolution' not allowed; "n": 2 даёт такую же ошибку для n. Так работает правило additionalProperties: false — если скопировать тело запроса из другой модели, лишние поля заблокируют весь вызов.
• В моём тесте seed не смог воспроизвести точно такое же изображение. Я дважды подряд отправил одинаковый промпт, seed: 42, aspect_ratio: 2.35:1 и creativity: medium. Оба раза вернулись корректные изображения 1568 × 672, но явно разные сцены (на одном белая башня, на другом красно-белая полосатая башня), разного размера файла (1,30 МБ против 1,51 МБ) и с разными хешами. Поле принимается и описано в документации как обеспечивающее воспроизводимость, но считайте точное попиксельное воспроизведение best-effort, а не гарантией — если вам нужен конкретный кадр, сохраните полученный результат и не запрашивайте заново с seed.

Связанные страницы

• Страница модели krea-2-medium-turbo — онлайн-playground и полный справочник параметров.
• Документация API krea-2-medium-turbo — эндпоинт и детали колбэков.
• Krea 3 преобразование текста в изображение — более новый тариф Krea с акцентом на качество (режимы berry/jam); используйте его, когда нужна большая детализация, а krea-2-medium-turbo — когда нужны скорость и низкая стоимость.
• API генерации изображений на hiapi — другие модели преобразования текста в изображение за тем же интерфейсом задач.

FAQ

Какие соотношения сторон можно запросить? Восемь: 1:1 (по умолчанию), 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3 и 9:16. Любое другое значение вернёт 400.

Можно ли за один вызов сгенерировать несколько изображений? Нет. Поля n нет, и схема отклоняет неизвестные свойства, поэтому каждый запрос генерирует ровно одно изображение. Для пакетной генерации отправляйте запросы в цикле (при желании с разными seed).

Что делает creativity? Он управляет тем, насколько буквально модель следует промпту: raw наиболее верен формулировке, high даёт максимум свободы интерпретации, low (по умолчанию) и medium находятся между ними.

Поддерживает ли krea-2-medium-turbo преобразование изображения в изображение или редактирование? Нет — только преобразование текста в изображение. В схеме нет image_urls / полей входного изображения. Если вам нужно преобразовать существующее изображение, используйте специализированные модели редактирования/преобразования изображения на hiapi.

Как долго действуют URL вывода? Они предоставляются из временного хранилища и истекают (в моём тесте примерно через семь дней). Скачивайте и переразмещайте изображения сразу после завершения задачи.