Создание изображений через APIVN API

Подключение к API

Отправляйте запросы на API URL сайта с заголовками Content-Type: application/json и Authorization: Bearer YOUR_API_KEY. Также поддерживается x-api-key.

Храните API key на сервере. В примерах используются переменные окружения; сами примеры не отправляют запросы от вашего имени.

read -r -s -p "STALI_API_KEY: " STALI_API_KEY
export STALI_API_KEY
printf '\n'
curl -fsS https://apivn.dev/v1/models -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}"

Выберите модель изображений

Используйте req/gpt-image-2 или req/gemini-3.0-pro-image. Если model отсутствует или пуст, оба эндпоинта изображений используют req/gpt-image-2.

Вызовите GET /v1/models, чтобы получить текущий каталог и pricing.per_request. API key должен разрешать выбранную модель.

Создание по описанию

Отправьте POST /v1/images/generations с model и описанием изображения в prompt. В примере используются n: 1 и size: 1024x1024. После завершения обработки эндпоинт возвращает JSON. stream принудительно установлен в false; SSE-поток не возвращается.

Примеры cURL рассчитаны на Bash в macOS, Linux или WSL. Для Python установите библиотеку командой pip install requests. Для Node.js используйте версию 18 или новее, сохраните код в файл .mjs и используйте встроенный fetch.

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/generations" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "A small botanical robot tending a seedling, studio product photography, soft natural light, clean ivory background, no text",
  "n": 1,
  "size": "1024x1024"
}'

Редактирование исходного изображения

Отправьте POST /v1/images/edits в формате JSON с непустым prompt и image. Изображение можно передать как data URL, строку base64 или общедоступный http(s) URL. В cURL замените https://example.com/reference.png реальным общедоступным URL изображения. Для Python или Node.js поместите reference.png в каталог, из которого запускаете пример.

Вместо image можно использовать image_url, reference_image, ref_image или refImage. Значение — строка или объект {url: ...}; рекомендуется передавать только одно поле изображения. Эндпоинт редактирования принимает JSON, а не multipart/form-data. URL изображения должен быть общедоступным и не содержать учетных данных; внутренние адреса блокируются. Для исходных изображений поддерживаются PNG, JPEG, WebP и GIF. Не вызывайте images.edit из SDK напрямую, если метод отправляет multipart/form-data. Этот эндпоинт требует JSON; примеры Python requests и Node.js fetch используют нужный формат.

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/edits" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "Keep the subject and composition, change the background to a warm ivory studio",
  "image": "https://example.com/reference.png",
  "n": 1,
  "size": "1024x1024"
}'

Параметры и ограничения

Размер всего JSON-запроса, включая закодированные изображения, не должен превышать 20 MiB. Base64 увеличивает объем данных. Ограничения Playground применяются отдельно.

Чтение и сохранение изображений

Читайте массив data в JSON-ответе. В зависимости от провайдера изображение находится в b64_json, b64Json или url. Дополнительные поля могут различаться у разных моделей.

{
  "data": [
    {
      "b64_json": "<base64 image bytes>"
    }
  ]
}

Если получен base64, декодируйте его в файл изображения или создайте data URL с MIME-типом фактического формата. Не считайте, что любой результат имеет формат PNG. Полученный URL можно использовать для загрузки или показа изображения. Срок действия и условия доступа зависят от провайдера.

Сохраняйте x-apivn-request-id для диагностики. Успешный ответ также содержит заголовки x-apivn-model, x-apivn-price-vnd-per-request и x-apivn-cost-vnd.

Оплата за запрос

Модели изображений оплачиваются за request. Перед запуском проверьте pricing.per_request в GET /v1/models: баланс или лимит расходов API key могут блокировать запрос. Количество токенов в ответе или заголовках не является основой для пересчета цены модели изображений. Новый запрос может привести к новому списанию.

Не повторяйте запрос автоматически после тайм-аута или разрыва соединения: предыдущий запрос мог быть обработан. Перед новым вызовом проверьте историю Usage и сохраните request ID для сверки или обращения в поддержку.

Осторожная обработка ошибок

Ошибки шлюза имеют вид {type: "error", error: {type, message, ...}}. Проверяйте HTTP-статус и error.message, сохраняйте request ID, если он доступен.

Перед отправкой запроса

Проверьте API key, разрешение на модель и текущую цену. Отправляйте JSON на правильный эндпоинт, ограничивайте объем данных и начните с одного изображения. Обрабатывайте base64 и URL, сохраняйте request ID и проверяйте результат перед повторным вызовом.

1. Проверьте API key и разрешения на модель.
2. Уточните модель и цену в /v1/models.
3. Проверьте JSON, prompt и данные изображения.
4. Поддерживайте результаты в base64 и по URL.
5. Проверьте историю Usage; сохраните request ID для сверки или обращения в поддержку.