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

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

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

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 в зависимости от запрошенного и поддерживаемого формата:

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

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

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. Успешная генерация не бывает пустой: ответ содержит хотя бы один пригодный элемент изображения.

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

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

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

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. Выберите доступную модель генерации, у которой каталог разрешает хотя бы одно промежуточное изображение, и отправьте запрос:

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]:

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

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

data: [DONE]

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

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 и разделитель:

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 означает, что сервис сейчас не может проверить сочетание по метаданным возможностей. Используйте точный код и актуальные значения каталога, а не подбирайте замену наугад.

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