API для генерации изображений: первый запрос и разбор ответа

Genius-bot · 6 минут чтения

Если нужен api для генерации изображений, полезно понимать не только как отправить запрос, но и что происходит после запуска задачи. На практике рабочий цикл обычно состоит из четырёх шагов: запуск генерации, получение идентификатора задачи, ожидание результата и скачивание готового файла по ссылке.

В API сервиса генерация изображения запускается отдельным запросом. Результат появляется не мгновенно: сначала создаётся задача, затем её состояние проверяется через отдельный маршрут. Поэтому при интеграции важно сразу закладывать логику ожидания завершения и сохранения итогового файла.

Получить API-ключ можно в разделе управления API-доступом. После входа ключ показывается один раз, а все запросы выполняются с заголовком Authorization: Bearer <ключ>.

Из чего состоит запрос на генерацию изображения

Для запуска операции используется маршрут POST /generate. Авторизация передаётся через Bearer-токен. Если требуется обычная генерация по текстовому описанию, используется операция image, стоимость которой составляет 9 ₽ за запуск.

Минимальный запрос обычно содержит название операции и параметры генерации. Конкретный набор параметров зависит от выбранной операции, поэтому перед интеграцией стоит получать актуальный список через маршрут GET /services.

Пример запуска задачи через api генерации изображений:

curl -X POST \
  https://genius-bot.ru/wp-json/genius/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "image",
    "prompt": "Красный ретро автомобиль на фоне гор"
  }'

После успешного запуска API возвращает информацию о созданной задаче. Её идентификатор понадобится для последующего получения результата.

Что приходит в ответе и сколько живёт ссылка

Сразу после запуска генерации обычно возвращается объект задачи. Далее состояние можно проверять через маршрут GET /tasks/{id}. Такой подход удобен для длительных операций: клиент не держит открытое соединение и может опрашивать статус по расписанию.

Также доступен альтернативный вариант через параметр callback_url. Если он указан при запуске, сервис отправит POST-запрос на указанный адрес после завершения обработки.

Когда задача готова, ответ содержит результат и ссылку на созданный файл. Именно эта ссылка используется для скачивания изображения и дальнейшей обработки в вашем приложении.

В документации сервиса не указано гарантированное время жизни ссылки. Поэтому при проектировании интеграции не стоит рассчитывать на её длительное хранение и доступность спустя недели или месяцы после генерации.

Скачивание и сохранение: почему сразу, а не потом

Самая частая ошибка при работе с image generation api — хранить только URL результата. Пока проект небольшой, это кажется удобным решением. Позже возникают проблемы с резервным копированием, миграцией данных и воспроизводимостью результатов.

Практический вариант — сразу после получения результата скачать файл и сохранить его в собственном хранилище. Тогда приложение не зависит от внешней ссылки и может гарантированно показывать изображение пользователям.

Типичный сценарий выглядит так:

1. Запустить генерацию.
2. Получить ID задачи.
3. Дождаться статуса готовности.
4. Получить ссылку на файл.
5. Скачать файл на свой сервер или в объектное хранилище.
6. Сохранить уже собственный URL в базе данных.

Такой подход одинаково хорошо работает, если нужно один раз сгенерировать картинку через api или обрабатывать тысячи задач в сутки.

Размеры и соотношения сторон

При работе с изображениями важно заранее определить, для какой площадки они создаются. Квадратные изображения подходят для карточек товаров и аватаров, вертикальные — для мобильных экранов, горизонтальные — для баннеров и обложек.

На стороне приложения полезно хранить информацию о целевом соотношении сторон вместе с запросом. Тогда при повторной генерации или обновлении контента не придётся подбирать параметры заново.

Если система получает изображения для разных сценариев, удобно выделить несколько стандартов:

Даже если генерация выполняется через один и тот же api для генерации изображений, требования к итоговому файлу могут существенно отличаться.

Форматы файла: где выигрывает png, где jpeg

После получения результата обычно возникает второй вопрос: в каком формате хранить изображение. Универсального ответа нет, поскольку PNG и JPEG решают разные задачи.

PNG лучше подходит для интерфейсов, схем, скриншотов и изображений с текстом. Формат сохраняет детали без потерь, но итоговый размер файла часто оказывается больше.

JPEG выигрывает в случаях, когда важен небольшой объём данных. Для фотографий, иллюстраций и превью это часто более практичный вариант.

Поэтому после того как удалось сгенерировать картинку через api, стоит сразу определить дальнейший сценарий использования и выбрать подходящий формат хранения.

Минимальный скрипт целиком

Ниже приведён упрощённый пример на Python с использованием requests. Он запускает задачу, получает её идентификатор, опрашивает состояние и скачивает итоговый файл после завершения обработки.

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://genius-bot.ru/wp-json/genius/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.post(
    f"{BASE_URL}/generate",
    headers=headers,
    json={
        "service": "image",
        "prompt": "Горный пейзаж на рассвете"
    }
)

task_id = response.json()["id"]

while True:
    task = requests.get(
        f"{BASE_URL}/tasks/{task_id}",
        headers=headers
    ).json()

    if task.get("status") == "completed":
        image_url = task["result"]["url"]

        image = requests.get(image_url)
        with open("result.jpg", "wb") as f:
            f.write(image.content)

        print("Saved:", image_url)
        break

    time.sleep(2)

При высокой нагрузке стоит учитывать ограничение частоты — не более 60 запросов в минуту на один ключ. Если задач много, лучше использовать webhook через callback_url, чтобы не выполнять постоянный опрос статуса.

Дополнительно полезно проверять баланс через GET /balance и список доступных операций через GET /services. Новый ключ можно получить в разделе личного кабинета API. При выпуске первого ключа на баланс начисляется 50 ₽ для тестирования.

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

Какой маршрут используется для генерации изображения?

Для запуска используется POST https://genius-bot.ru/wp-json/genius/v1/generate с авторизацией через Bearer-токен.

Как узнать, что задача завершилась?

Можно проверять состояние через GET /tasks/{id} либо передать callback_url и получить уведомление POST-запросом после завершения.

Сколько стоит генерация изображения?

Операция «Картинка по описанию» (image) стоит 9 ₽ за один запуск.

Нужно ли сохранять результат у себя?

Да. Практика интеграций показывает, что надёжнее сразу скачивать готовый файл и хранить его в собственной инфраструктуре, а не только ссылку на результат.

Есть ли абонентская плата?

Нет. Оплата выполняется за запуски операций. Минимальный платёж отсутствует.

Какой лимит запросов действует для одного ключа?

Не более 60 запросов в минуту на один API-ключ.

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

Получить ключ