- Через API можно генерировать растровые изображения и векторы, обрабатывать исходные файлы, менять фон, удалять его, векторизовать и увеличивать разрешение.
- Создайте учётную запись Recraft, откройте настройки API и выпустите токен.
- Для первого теста отправьте POST на адрес https://external.api.recraft.ai/v1/images/generations с заголовками Authorization: Bearer и Content-Type: application/json.
- Успешный ответ содержит список созданных изображений в поле data и расход API Units.
- Фронтенд отправляет запрос вашему серверу с описанием изображения и выбранным форматом.
Recraft API нужен, когда изображения должны создаваться автоматически: в личном кабинете клиента, админке интернет-магазина, внутреннем инструменте дизайнера или сервисе генерации иконок. Вместо ручного ввода запроса в Recraft Studio приложение отправляет HTTPS-запрос и получает ссылку на результат. Для стабильной интеграции важно правильно хранить токен, учитывать стоимость операций, скачивать итоговый файл и ограничивать число запросов. Ниже — рабочая схема первого подключения.
Что поддерживает API
Через API можно генерировать растровые изображения и векторы, обрабатывать исходные файлы, менять фон, удалять его, векторизовать и увеличивать разрешение. Доступны разные модели и способы создания графики. Для карточек товаров подойдёт растровая генерация или редактирование фона, для иконок — векторный вывод, для автоматизированных баннеров — шаблон с фиксированным промптом и последующим добавлением текста. Выбор операции влияет на цену и формат ответа. Параметры моделей следует сверять с актуальной документацией при разработке.
Как получить ключ доступа
Создайте учётную запись Recraft, откройте настройки API и выпустите токен. Для работы нужен положительный баланс API Units. Ключ используется в заголовке Authorization по схеме Bearer. Никогда не вставляйте его в HTML страницы, фронтенд-код, публичный репозиторий или URL изображения. На сервере храните токен в переменной окружения или менеджере секретов, а при подозрении на утечку заменяйте. Разные ключи одного аккаунта могут использовать общий баланс, поэтому отдельный токен сам по себе не создаёт бюджетный лимит для конкретного отдела.
Минимальный запрос на генерацию
Для первого теста отправьте POST на адрес https://external.api.recraft.ai/v1/images/generations с заголовками Authorization: Bearer <API_TOKEN> и Content-Type: application/json. В теле JSON передайте поле prompt, например описание плоской иллюстрации рабочего стола. Если модель не указана, API использует модель по умолчанию, которая может изменяться. Для воспроизводимых результатов выбирайте конкретный идентификатор модели и фиксируйте его в настройках проекта. Удостоверьтесь, что сервер не пишет сам токен в логи.
Как разобрать ответ
Успешный ответ содержит список созданных изображений в поле data и расход API Units. Ссылка на файл может быть временной: по документации Recraft хранит такие файлы около 24 часов. Поэтому недостаточно просто записать URL в базу данных. Ваш сервер должен скачать изображение, проверить тип содержимого и размер, сохранить его в собственном объектном хранилище и связать с заданием пользователя. Если хранение невозможно, сообщайте пользователю об ограниченном времени жизни результата. Не принимайте непроверенные адреса загрузки из клиентского браузера как доверенные.
Как встроить генерацию в интерфейс
Фронтенд отправляет запрос вашему серверу с описанием изображения и выбранным форматом. Сервер проверяет длину и допустимость промпта, наличие средств у пользователя и лимиты операций. Затем делает запрос к Recraft и создаёт запись задания с состоянием ожидания или успеха. После получения ответа сохраняет файл и возвращает клиенту собственную ссылку. Для длительных операций удобна очередь задач, иначе браузер может показать ошибку тайм-аута, хотя генерация завершилась. Повторные запросы должны быть защищены от случайного многократного списания.
Ошибки, безопасность и расходы
Обрабатывайте отдельно ошибки авторизации, нехватку единиц, некорректные параметры, временную недоступность и ограничения частоты запросов. Не повторяйте запрос бесконечно: используйте ограниченное число попыток с задержкой и сохраняйте идентификатор задания. Установите дневной бюджет API Units и предупреждение при приближении к лимиту. Проверяйте размер и тип загружаемых файлов, защищайте место хранения и запрещайте клиенту напрямую вызывать платный API своим запросом. При открытом публичном интерфейсе потребуются защита от спама и ограничение пользовательских квот.
API Units и кредиты Studio
Единицы API покупаются отдельно от кредитов обычной подписки Recraft Studio. Стоимость зависит от модели и операции: векторная генерация, исправление области или увеличение разрешения могут обходиться по-разному. Не рассчитывайте API-бюджет только по числу пользователей: учитывайте среднее количество попыток до удачного результата, вероятность ошибок и повторные обращения. Для предварительной оценки заведите таблицу с типом операции, количеством вызовов и расходом единиц. О подписках редактора подробно рассказано в разборе тарифов.
Пример архитектуры для интернет-магазина
Предположим, сотрудник загружает фотографию товара и выбирает «Сделать нейтральный фон». Сервер принимает файл, проверяет размер и права доступа, сохраняет исходник, вызывает нужную операцию API и получает обработанный результат. Изображение попадает в очередь проверки: сотрудник сопоставляет этикетку и форму товара с оригиналом. После одобрения файл отправляется в каталог. Автоматическая публикация без проверки рискованна, поскольку модель может изменить важные детали. Для рекламных изображений также проверяйте коммерческие права и лицензию исходной фотографии.
Что сделать перед запуском в рабочей среде
Проведите тест на десятках разноплановых изображений, измерьте время ответа, количество ошибок, стоимость одной принятой картинки и нагрузку на хранение. Отдельно проверьте восстановление после тайм-аута и невозможность повторного списания при обновлении страницы. Запланируйте ротацию токенов и удаление временных файлов с персональными данными. Для генерации SVG убедитесь, что результат безопасно обрабатывается перед вставкой на сайт и не содержит потенциально опасного содержимого. Для коммерческого применения изучите правила использования результатов.
Полный пример первого запроса через Python
С ноября 2026 года ключи и учёт расхода доступны в API Portal по адресу recraft.ai/app/api. Там находятся баланс API Units, журнал запросов, CSV-экспорт, статистика ошибок 4xx/5xx и задержек p50/p95, управление ролями команды и отзыв токенов. В этом кабинете отслеживаются запросы с API-ключами, а не операции Recraft Studio. Для работы нужен положительный баланс API Units, оплачиваемый отдельно от подписки Studio.
Установите requests командой python -m pip install requests. Создайте переменную окружения RECRAFT_API_TOKEN со своим секретным ключом. Сохраните следующий пример в файл recraft_test.py и запустите из терминала командой python recraft_test.py:
import os
import requests
api_key = os.environ["RECRAFT_API_TOKEN"]
response = requests.post(
"https://external.api.recraft.ai/v1/images/generations",
headers={"Authorization": f"Bearer {api_key}"},
json={
"prompt": "Minimal flat illustration of a teacup, two colors",
"model": "recraftv4_1_flash_v2",
"n": 1,
},
timeout=120,
)
response.raise_for_status()
result = response.json()
print("Image URL:", result["data"][0]["url"])
print("API units:", result.get("credits"))
На успешном ответе программа печатает ссылку на картинку и расход API Units, если поле credits присутствует. Пример описывает ожидаемую обработку ответа; редакция не запускала оплаченный запрос на вашем ключе. Сохраните полученный файл в собственном хранилище: выдаваемые сервисом ссылки могут действовать ограниченное время.
При ошибке 401 проверьте, что переменная окружения содержит действующий токен; при 402 или проблеме баланса — пополнение API Units; при 429 — ограничение частоты запросов. При 4xx не повторяйте ту же операцию автоматически без исправления параметров, при 5xx используйте ограниченные повторы с задержкой и мониторингом расходов. Никогда не передавайте ключ браузеру. Для конечного пользователя отдельно нужны проверка промптов, лимиты и очередь задач. Сравнить автоматизацию с ручной работой поможет материал о Recraft для бизнеса.