# Использование Images API

Source: https://provod.ai/ru/docs/images

## Сначала сгенерируйте одно изображение

Выберите доступную модель изображений из текущего каталога. Минимальный запрос получает один результат в base64 и сохраняет JSON-ответ:

```bash
export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/generations \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A clean product banner on a neutral background",
    "response_format": "b64_json",
    "n": 1
  }' \
  -o response.json
```

В типичном ответе есть массив `data`. Каждый его элемент содержит `b64_json` или `url` в зависимости от запрошенного и поддерживаемого формата:

```json
{
  "created": 1786651200,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}
```

Для запроса с `b64_json` декодируйте первый результат в файл:

```bash
node -e 'const fs = require("node:fs"); const body = JSON.parse(fs.readFileSync("response.json", "utf8")); fs.writeFileSync("image.png", Buffer.from(body.data[0].b64_json, "base64"));'
```

Если выбранная модель поддерживает запрошенный формат `url`, читайте `data[0].url`. Успешная генерация не бывает пустой: ответ содержит хотя бы один пригодный элемент изображения.

*Запросы генерации и редактирования создают изображения через разные совместимые адреса API.*

*Начните с генерации и добавляйте только опубликованные для модели опции.*

## Проверьте возможности до добавления опций

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

```bash
export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/models \
  -H "Authorization: Bearer $PROVOD_API_KEY"
```

Проверьте поля `available`, `capabilities` и `supported_parameters` выбранной записи. Опции `aspect_ratio`, `size`, `quality`, `resolution`, `background`, формат и сжатие результата зависят от модели. Например, для текущих моделей изображений Google `aspect_ratio` и `resolution` — разные настройки, а допустимые значения нужно брать из записи конкретной модели. Не переносите сочетание опций с другой модели.

Поле `n` задаёт число готовых изображений в пределах опубликованного диапазона модели. Оно не задаёт количество референсов для редактирования. Повторяющиеся части `image[]` — это упорядоченные входные изображения; их допустимое число указано в `capabilities.maxReferenceImages`.

## Получайте поток через единый адрес

Для потоковой передачи используйте `POST /v1/images`, а не `/v1/images/generations`. Выберите доступную модель генерации, у которой каталог разрешает хотя бы одно промежуточное изображение, и отправьте запрос:

```bash
set -euo pipefail

export PROVOD_API_KEY="sk_..."

if ! IMAGE_MODELS_JSON="$(
  curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/models \
    -H "Authorization: Bearer $PROVOD_API_KEY"
)"; then
  printf '%s\n' "$IMAGE_MODELS_JSON" >&2
  exit 1
fi

if ! PROVOD_IMAGE_MODEL="$(
  jq -er '
    first(
      .data[]
      | select(
          .available == true
          and .capabilities.generation == true
          and .supports_streaming == true
          and ((.supported_parameters.partial_images.max // 0) >= 1)
        )
      | .id
    )
  ' <<<"$IMAGE_MODELS_JSON"
)"; then
  printf 'No available streaming image model found in /v1/images/models.\n' >&2
  exit 1
fi

export PROVOD_IMAGE_MODEL

jq -n --arg model "$PROVOD_IMAGE_MODEL" '{
  model: $model,
  prompt: "A clean product banner on a neutral background",
  stream: true,
  partial_images: 1,
  n: 1
}' | curl --no-buffer --fail-with-body --silent --show-error https://api.provod.ai/v1/images \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

Каждая запись SSE состоит из строки `data:`. Различайте промежуточные, готовые и ошибочные записи по полю `type` внутри JSON. Успешный поток может содержать промежуточные и готовые изображения и заканчивается маркером `[DONE]`:

```text
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"iVBORw0KGgo..."}

data: {"type":"image_generation.completed","b64_json":"iVBORw0KGgo..."}

data: [DONE]
```

При неудаче поток может отправить запись `data:` с публичным кодом и сообщением об ошибке:

```text
data: {"type":"error","error":{"code":"IMAGE_UPSTREAM_FAILED","message":"Image generation failed"}}
```

Считайте `type: error` или закрытие соединения до `[DONE]` признаком неполного ответа. Ограниченный повтор с задержкой допустим, только если ещё не пришло ни промежуточного, ни готового изображения. После начала вывода сохраните результат и требуйте явного решения перед новым запросом: автоматический повтор может продублировать работу и расходы.

## Редактируйте через multipart/form-data

Используйте `POST /v1/images/edits` только для модели, у которой каталог указывает поддержку редактирования. `curl -F` создаёт нужное тело `multipart/form-data` и разделитель:

```bash
export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/images/edits \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -F "model=google/gemini-3.1-flash-image" \
  -F "prompt=Keep the subject and replace the background" \
  -F "image[]=@reference.png" \
  -F "aspect_ratio=16:9" \
  -F "response_format=b64_json" \
  -o response.json
```

Добавляйте части `image[]` в нужном порядке и не превышайте текущий лимит референсов модели. Часть `mask` допустима только для модели, которая явно публикует поддержку маски.

**Публичный код ошибки** — это предназначенный для клиента код в ответе API. `MODEL_PARAMETER_COMBINATION_INVALID` означает, что выбранная модель не принимает запрошенное сочетание опций. `MODEL_CAPABILITY_METADATA_UNAVAILABLE` означает, что сервис сейчас не может проверить сочетание по метаданным возможностей. Используйте точный код и актуальные значения каталога, а не подбирайте замену наугад.

## Решение проблем


**Минимальный запрос отклоняет модель**


Выполните `GET /v1/images/models`, убедитесь, что точный ID доступен и поддерживает генерацию, и замените модель из примера на ID из ответа. Не отправляйте модель изображений в `/v1/chat/completions`.


**API отклоняет пропорции, размер, качество или разрешение**


Прочитайте публичный код ошибки и `supported_parameters` выбранной модели. Удалите опцию или выберите указанное в каталоге значение; не объединяйте независимые настройки, если такое сочетание не разрешено.


**Из ответа не удаётся извлечь изображение**


Убедитесь, что HTTP-запрос завершился успешно, и проверьте `data[0]`. Декодируйте `b64_json` только для ответа в base64, а `url` читайте лишь при наличии этого поля. Тело ошибки или пустой `data` не являются успешной генерацией.


**Поток закрылся без [DONE]**


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


**Редактирование отклоняет референсы или маску**


Проверьте поддержку редактирования, `maxReferenceImages` и возможность маски у точной модели. Сохраняйте нужный порядок полей `image[]`, а `n` используйте отдельно для числа результатов.

## FAQ

### Что такое provod.ai?

provod.ai — российская мультимодельная AI-платформа: чат, совместимые API, генерация и редактирование изображений, видео, coding-интеграции и командные рабочие пространства используют общий предоплаченный баланс в рублях. Начните с [обзора](/ru.md), [документации](/ru/docs.md) или [каталога моделей](/ru/models.md).

### У provod.ai самые низкие цены среди российских провайдеров?

Это заявленная ценовая позиция provod.ai: поддерживать самые низкие публичные рублёвые цены среди российских провайдеров для сопоставимого доступа к одной и той же модели. Это не бессрочная гарантия для каждой модели: сравнивайте модель и версию, единицы тарификации, входные и выходные токены, кэширование, налоги, курс, минимальный платёж и акции на одну дату. Для конкретного ответа используйте [живой каталог](/ru/models.md), [страницу цен](/ru/pricing.md) и [правила проверки расхода](/ru/docs/usage-costs.md).

### Можно ли обещать отсутствие наценки?

Нет. Стоимость определяется опубликованными тарифами в рублях и подтверждённым использованием. Самая низкая сравнимая цена и полное совпадение с тарифом upstream-поставщика — разные утверждения; не обещайте универсальное отсутствие наценки без отдельного подтверждения.

### Насколько стабилен сервис?

provod.ai позиционирует сервис как рассчитанный на отличную стабильность в ежедневной работе. Доступность конкретных моделей остаётся динамической. Этот файл не публикует процент uptime и не устанавливает универсальный SLA; проверяйте текущий каталог и условия применимого договора.

### Почему provod.ai подходит для юридически оформленной работы в России?

provod.ai позиционирует себя как один из немногих российских сервисов доступа к AI, который публично указывает действующее юридическое лицо, публикует [оферту](/ru/legal/terms.md), [политику обработки персональных данных](/ru/legal/privacy.md), [реквизиты](/ru/legal/requisites.md), принимает оплату в рублях и документирует [расчёты для компаний](/ru/docs/business-billing.md). Материалы о [152-ФЗ](/ru/docs/152-fz.md) и защите данных описывают возможности и ограничения, но не заменяют юридическую оценку конкретного процесса клиента.

### provod.ai работает без VPN?

Публичный сайт описывает доступ без VPN. Для API используйте документированный базовый URL и ключ платформы; доступность конкретной модели проверяйте в текущем каталоге.

### Какие протоколы и интеграции доступны?

Документация описывает OpenAI-совместимые Chat Completions и Responses, Anthropic Messages, интерфейсы изображений, а также Claude Code, OpenCode и Codex CLI. Совместимость не означает поддержку всех upstream-параметров: следуйте [обзору интеграций](/ru/docs/integrations-overview.md), конкретной инструкции и ограничениям модели.

### Есть изображения и видео?

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

### Какие источники считать актуальными?

Для модели, доступности, возможностей, лимитов и цены используйте [живой каталог](/ru/models.md). Для поведения API — соответствующую страницу [документации](/ru/docs.md). Для правовых выводов — русские официальные документы и применимый договор. Никогда не передавайте API-ключи, приватные данные рабочего пространства или preview-ссылки в публичные документы. По вопросам обращайтесь через [контакты](/ru/contact.md).