POST /v1/images/generations

Создайте изображение включённой моделью с проверенным маршрутом image.generate. Проверьте доступные параметры и тарифы через GET /v1/images/catalog?model=YOUR_MODEL; названия моделей и промпты в примерах ниже не означают преднастроенные продукты.

Запрос

Выполнение команды с настоящим ключом и поддержанной моделью может привести к списанию. Для каждого создания нужен новый Idempotency-Key, выбранный приложением; сохраняйте его для повторов того же запроса.

curl https://api.model-gate.com/v1/images/generations \
  -H "Authorization: Bearer $MODEL_GATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: illustration-001' \
  -d '{"model":"YOUR_MODEL","prompt":"A clean isometric server gateway illustration","n":1,"model_gate":{"async":true}}'

При model_gate.async: true сервер возвращает HTTP 202 и image.operation с идентификатором, статусом и URL результата. Без него сервер ждёт до 55 секунд, затем возвращает готовое изображение, явную ошибку поставщика или операцию HTTP 202 для опроса. Верхнеуровневый async, потоковый режим, неизвестные параметры, повторные поля JSON и несовместимые настройки отклоняются.

Ответ и получение результата

Пример фрагмента ответа HTTP 202 (временные отметки и другие поля операции опущены):

{"object":"image.operation","id":"01K5P0Y3S80X8GFH1Q9WXQK7BX","status":"queued","result_url":"/v1/images/operations/01K5P0Y3S80X8GFH1Q9WXQK7BX/result"}

Вызывайте GET /v1/images/operations/{id} с тем же активным API-ключом. Готовый результат доступен по GET /v1/images/operations/{id}/result; по умолчанию возвращаются только created и data. Добавьте ?view=details для прежних метаданных model_gate. Каждый результат обычно содержит b64_json. Если маршрут поддерживает response_format: url, URL относится к этому шлюзу и всё равно требует аутентификации. Не рассчитывайте на публичный URL поставщика.

Повтор идентичного запроса с тем же Idempotency-Key не запускает новую генерацию. Другой запрос с тем же ключом возвращает HTTP 409. При outcome_unknown или review_required остановитесь и запросите расследование оператора: замена ключа может оплатить дубликат. Ошибка скачивания рассматривается отдельно; для неё доступен повтор только скачивания из раздела операции с изображениями.

Цена не определяется по длине base64. Неизвестная токенная стоимость остаётся неизвестной; предварительного резервирования в кошельке нет. Зафиксированная запись учёта отличается от последующего финансового расчёта кошелька. Файлы хранятся 24 часа, а операция остаётся доступной для идемпотентного воспроизведения. Используйте обычный API-ключ, не ключ браузерного сеанса. Выделенная вкладка Images в Playground доступна с 10.49.0.

Для исходных изображений и необязательных масок см. POST /v1/images/edits.

Необязательное model_gate.quote_sha256 связывает запуск с ранее согласованным расчётом цены маршрута; изменение контекста отклоняется до отправки. Вкладка Images использует ограниченные разрешения, не раскрывая постоянные секреты API.

Поля цены и использования

В явном подробном представлении fixed_quote незавершённой операции — предварительная цена, а не списание. Измеренная сохранённая стоимость показывается как Calculated cost; accounting_recorded всё ещё не доказывает обновление баланса. files_available равен true только при наличии сохранённых выходных файлов с неистёкшим сроком хранения. Отсутствие файлов во время ожидания не означает, что срок их хранения истёк.

Некоторые результаты с оплатой за изображение сообщают только общие количества токенов. Тогда usage может содержать token_usage_status: aggregate_only_not_priced и reported_tokens с input_tokens, output_tokens, total_tokens и необязательным cached_tokens. Это наблюдаемые общие значения, не разбивка токенов на текст/изображения; отсутствие категории не означает наблюдаемый ноль. Для токенной цены всё ещё нужны достаточные usage-данные. Недействительные или противоречивые результаты остаются review_required; обратитесь в поддержку без новой генерации.

Обычные ответы ожидающих и выполняющихся операций не содержат расчётных и пустых полей. Читайте операцию с ?view=details, чтобы увидеть quote, usage и settlement. Создание из Playground не передаёт max_cost_usd, сохраняя привязку маршрута/расчёта цены и Idempotency-Key.

Ошибки запросов изображений

Ошибки содержат стабильный error.code, понятный error.message, error.type и, где применимо, error.param. Сохраните X-Request-ID из ответа для поддержки; не отправляйте API-ключ. Неизвестная каноническая модель или псевдоним возвращают 400 model_not_found, а не ошибку доступности каталога.

Ограничения нескольких маршрутов не объединяются в выдуманные допустимые комбинации. Не повторяйте платный POST автоматически после тайм-аута или неоднозначной ошибки. Проверьте статус операции и сохраните исходный ключ идемпотентности. Подробные внутренние ошибки конфигурации и учётных данных клиенту не возвращаются.

Конечные ошибки поставщика (14.11.2)

Полная распознанная ошибка поставщика без изображения получает status: failed, в том числе если поставщик ошибочно вернул HTTP 200. Синхронное создание и повтор уже ошибочной операции возвращают соответствующий ошибочный HTTP-статус, объект error и идентификатор принятой операции. Например, image_generation_failed использует HTTP 502 и error.type: image_generation_error; ошибки параметров или политики контента — 400, лимит запросов поставщика — 429.

Успешное чтение состояния остаётся HTTP 200 с тем же статусом failed и безопасной ошибкой. billing_review_required — отдельный признак учёта; он не превращает ошибку в ожидающую генерацию и не разрешает новый платный POST. Сохраняйте Location, X-Request-ID и исходный Idempotency-Key. Полные правила ответа и повторов приведены в разделе ошибки и расчёты операций изображений.