Операции с изображениями и файлы

Создание возвращает сохраняемую операцию, даже если клиент перестал ждать. Продолжайте использовать тот же активный API-ключ. Доступ к операциям и выходным файлам ограничен владельцем, инициатором, API-ключом и текущей группой: одного подобранного идентификатора недостаточно.

Состояния queued и preparing ещё не пересекли границу платной отправки. Операцию в состоянии dispatching нельзя автоматически возвращать для нового POST. Сохранённый ответ поставщика проходит состояния received и retrieving до completed. Состояние failed завершает операцию без новой автоматической попытки; истечение срока очереди отображается как failed с error_code queue_expired, а не как отдельный статус expired.

outcome_unknown означает, что шлюз не может безопасно определить результат платного POST. review_required означает, что ответ или сведения о цене требуют проверки. Ни одно из этих состояний не разрешает начать заново с новым Idempotency-Key. Обратитесь к оператору; автоматическая сверка результатов в этом выпуске не реализована.

При retrieval_failed используйте эндпоинт повторного скачивания не более пяти раз до истечения 24-часового срока хранения файлов. Он читает уже сохранённый ответ поставщика, не выполняет генерацию и не учитывает стоимость повторно. Чтение и повторное получение сохранённого результата не требуют новой оплаты инференса. Файлы удаляются по сроку хранения, но отметки идемпотентности остаются, чтобы старый ключ никогда незаметно не запускал новый запрос.

Предварительного резервирования нет. accounting_recorded означает фиксацию записи для существующего процесса расчётов, а не гарантирует, что баланс уже обновлён. Цена по токенному тарифу остаётся неизвестной до получения пригодных данных об использовании от поставщика. Playground больше не отправляет model_gate.max_cost_usd. Необязательное устаревшее поле по-прежнему распознаётся только при доказуемой фиксированной цене.

Playground и потерянные HTTP-ответы (10.49.0)

Playground Images использует отдельные разрешения чтения, создания и повтора скачивания с текущими правами сотрудника/ключа. Ограничения старых браузерных ключей не ослабляются. Сохранённая операция может продолжиться после истечения короткого разрешения, но требования к текущей сессии, ключу и доступу сохраняются.

GET /v1/images/operations?idempotency_key=... — поиск без записи в той же области идентичности/ключа. Совпавшая операция возвращает сохранённый публичный статус; при отсутствии видимого совпадения возвращается submission_found:false. Это не сигнал автоматически создавать другое намерение: исходное принятие ещё может выполняться. Сохраняйте тот же ключ/намерение и проверяйте историю. Поиск не создаёт токен, тело, расчёт цены или списание.

Чтение GET /v1/images/catalog?model=...&operation=... показывает отдельные проверенные предложения маршрутов, а не гарантирует работоспособность поставщика. POST /v1/images/quote нормализует поддерживаемые настройки и возвращает хеш согласования без списания. Список и прямые эндпоинты создания остаются доступны обычным API-клиентам.

Каталог и сохранённые поля

GET /v1/images/catalog требует model; operation по умолчанию равно image.generate и также принимает image.edit. Ответ содержит object:list, отдельные предложения data, runtime_limits и provider_health_verified:false. Пустой список data означает отсутствие пригодного проверенного предложения, а не результат проверки работоспособности поставщика. Для каждого предложения показаны маршрут, модель, операция, редакция, хеш и срок действия контракта, ограничения запроса, выбранный тариф и коэффициенты. Учётные данные поставщика не возвращаются.

Ответ с явно указанным ?view=details включает object:image.operation, id, operation, model, status, Unix-время created и files_expires_at, files_available, error_code, quote, usage, accounting_recorded, accounting_note, files, result_url и download_retry_allowed. Описание каждого файла содержит индекс, относительный URL, SHA-256, MIME, размер в байтах и размеры изображения. Само по себе неистёкшее время хранения не гарантирует, что выходной файл уже создан. Исходные изображения через эндпоинт выходных файлов не выдаются.

История отсортирована по убыванию ID операции, не по времени внешних идентификаторов; максимум 50 записей. before нельзя сочетать с idempotency_key. Поиск возвращает список из нуля или одного элемента и submission_found; отсутствие результата не доказывает отклонение выполняющегося создания. Чужие ресурсы не раскрываются.

Расчёт цены и суммы для Usage Limit — предварительные значения. Вычисленная стоимость также отличается от завершённого изменения баланса. Доступность сохранённых файлов требует существующего файла и неистёкшего окна скачивания. Общие количества токенов могут появляться в reported_tokens с token_usage_status=aggregate_only_not_priced; они не заменяют отсутствующую разбивку по модальностям для токенной тарификации. См. поля ответа генерации.

Финансовый расчёт и сохранённые ответы поставщика

GET отдельной операции и поиск по идемпотентности с ?view=details включают доступный только для чтения объект settlement с той же областью доступа по владельцу, инициатору, ключу и группе. В нём есть status, record_found, Unix-время settled_at, wallet_debited, usage_applied и Unix-время observed_at. Неизвестные наблюдения представлены JSON null. Состояния pending/failed не подтверждают завершённое списание; settled/recovered с временной отметкой и положительной записанной стоимостью подтверждают зарегистрированное событие расчёта. not_required отличается от неуспешного поиска. not_available означает отсутствие соответствующей записи учёта, возможно из-за истечения срока хранения; unavailable означает ошибку наблюдения. Ни одно не означает бесплатное выполнение. Для строк истории, которые не проверялись, возможен not_checked; прочитайте отдельную операцию для свежего наблюдения. Само наблюдение не создаёт платёж, возврат или резервирование.

supplier_http_status — сохранённый статус поставщика (0 до его появления), а response_saved указывает на зарегистрированное время ответа. Это не HTTP-статус данного API GET или исходного ответа 202 о постановке в очередь. Сохранённый 5xx не доказывает отсутствие расходов у поставщика. Не отправляйте повторно автоматически платный запрос с неизвестным исходом.

Краткий статус и детали расчёта

Начиная с версии 11.0.0, ответы операций по умолчанию компактны: object, id, model, status, created, status_url, result_url. Значимый error_code или сообщённый прогресс включается только при наличии. Завершённые результаты содержат доступность, срок действия и необходимые описания файлов. Пустые поля, расчёт цены, нормализованное usage, settlement и диагностика поставщика опускаются. Отсутствие поля не означает нулевую стоимость или завершённое списание.

Для прежнего полного разрешённого представления расчёта используйте GET /v1/images/operations/{id}?view=details. Списки и перечни результатов также поддерживают явный режим деталей там, где применимо. Чтение деталей не генерирует медиа и не расширяет доступ. Эндпоинт quote остаётся отдельным способом просмотра цены без списания.

Чтение результата: Raw и cURL

Используйте тот же активный API-ключ и контекст пользователя, с которыми создана операция. Другой ключ того же аккаунта не наследует результат автоматически. Текущие права и ограничения домена/IP проверяются снова. Возьмите OPERATION_ID из ответа принятой операции или разрешённой истории, а MODEL_API_KEY задайте локально, не публикуя секрет. Временное разрешение Playground не является многократно используемым CLI-ключом; копирование команды не экспортирует и не расширяет это разрешение.

GET https://api.model-gate.com/v1/images/operations/{id}/result
Authorization: Bearer <YOUR_API_KEY>

# status
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/images/operations/${OPERATION_ID:?Set OPERATION_ID}" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output images-status.json

# result
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/images/operations/${OPERATION_ID:?Set OPERATION_ID}/result" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output images-result.json

# first image (only when descriptor index 0 exists)
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/images/operations/${OPERATION_ID:?Set OPERATION_ID}/files/0" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output image-0.bin

/result возвращает сохранённый JSON created/data. Файловый эндпоинт возвращает байты изображения, а не этот JSON. Выберите существующий index с нуля из описаний файлов операции и расширение по MIME-типу; в примере используется .bin, чтобы не предполагать PNG. Playground подставляет подходящее расширение для каждого доступного изображения.

Это GET-запросы без тела: не нужны Content-Type, Idempotency-Key, расчёт цены, route_id или max_cost_usd. Читайте статус до завершения, затем результат/файл. Ответы ожидания, ошибки, истёкшего срока и отказа в доступе — не выходные файлы; --fail-with-body возвращает ненулевой код при HTTP-ошибке, но может записать её тело под выбранным именем. Проверяйте статус и тип содержимого, прежде чем считать загруженное тело медиафайлом. Не повторяйте платный POST из-за ошибки GET.

Блок Playground Get the result · Raw / cURL формирует эти команды для выбранной операции и её исходного ключа. Это примеры нового чтения, а не запись прежнего HTTP-обмена. Копирование и переключение вкладок команд не отправляют сетевых запросов. Открытие истории или сохранённого результата выполняет обычное разрешённое чтение, но не новую генерацию, резервирование или списание.

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

Полный ответ с ошибкой поставщика без изображения означает конечный статус операции failed. Это относится и к распознанной ошибке, которую поставщик прислал с HTTP 200 или 5xx. Повреждённый, неполный или противоречивый ответ остаётся неопределённым; сочетание ошибки с результатом или признаками продолжающейся работы не считается однозначным отказом.

Операция содержит безопасный объект error с message, type и публичным code. Произвольный текст ответа и секреты поставщика клиенту не передаются. Сохраняйте id, status_url, Location и X-Request-ID для обращения в поддержку. Внутренний error_code остаётся диагностическим идентификатором.

Если однозначный отказ получен во время синхронного ожидания, ответ использует указанный ошибочный HTTP-статус и сохраняет поля принятой image.operation вместе с error. Идентичный повтор с исходным Idempotency-Key возвращает ту же ошибочную операцию, в том числе при запросе async-режима. Новая принятая асинхронная операция по-прежнему возвращает 202. GET /v1/images/operations/{id} возвращает HTTP 200 с status: failed и error, поскольку состояние успешно прочитано. /result возвращает соответствующую ошибку и после истечения обычного срока доступности файлов. Несуществующее изображение для ошибочной операции не объявляется доступным.

billing_review_required: true означает, что учёт работы поставщика для неудачной генерации требует проверки. Этот признак отделён от статуса генерации и settlement.status. Полный отказ поставщика с 4xx, кроме 408, не устанавливает этот признак. Значение false или отсутствие учётной записи сами по себе не доказывают нулевую стоимость или завершённый расчёт. Для проверки расчётов открывайте разрешённые подробности операции.

Автоматического платного повтора нет. Новая генерация требует отдельного явного действия; сохраняйте исходную операцию и проверяйте неопределённые расходы перед решением о повторе. Обновление приложения не переписывает прежние неопределённые операции или их финансовую историю.