Генерация изображений для задач компании

POST /v1/images/generations создаёт устойчивую операцию Images. Используйте API-ключ компании и модель с проверенным контрактом image.generate. Инструмент image_generation в Responses имеет отдельный контракт API и не использует это хранилище операций.

Запрос

Выполнение примера с настоящей моделью и ключом может быть платным. Замените модель и перед отправкой изучите GET /v1/images/catalog?model=YOUR_MODEL. Параметры зависят от выбранного маршрута.

curl https://api.b2b-llm.com/v1/images/generations \
  -H "Authorization: Bearer $B2B_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: company-label-001' \
  -d '{"model":"YOUR_MODEL","prompt":"A plain product label on a neutral background","n":1,"model_gate":{"async":true}}'

Ответ и границы доступа

Асинхронное подтверждение — HTTP 202 с object: image.operation, идентификатором операции id, полями status, quote и result_url. Опрашивайте URL операции с аутентификацией. GET /v1/images/operations/{id}/result возвращает завершённую структуру created/data или текущее состояние. Закодированный результат находится в b64_json; поддерживаемый response_format: url возвращает закрытые относительные URL файлов, а не URL поставщика. Для скачивания передавайте API-ключ компании.

Доступ связан с владельцем списания, исходным principal, исходным API-ключом и текущим контекстом группы. Ключ другого сотрудника не даёт права просматривать все файлы компании. Старые ключи браузерного сеанса не принимаются. С версии 10.49.0 отдельная вкладка Images в Playground вместо этого использует разрешения на конкретную операцию, не раскрывая постоянный ключ проекта.

Идентичный повтор с тем же Idempotency-Key возвращает существующую операцию; изменение содержимого даёт HTTP 409. Не меняйте ключ для обхода outcome_unknown или review_required: перед новым платным запросом нужно расследование. Только retrieval_failed допускает явный повтор исключительно скачивания.

Предварительного резервирования баланса нет. accounting_recorded означает фиксацию канонической записи usage, а не завершённый финансовый расчёт. При отсутствии данных о токенах цена остаётся неизвестной вместо выдуманного нуля. Файлы истекают через 24 часа; записи идемпотентности сохраняются. См. обработку операций и редактирование.

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

Чтение расчётной стоимости операции

В запросах компании различайте предварительные Price quote и Usage Limit quote и фактические Calculated cost и сумму для лимита, записанные после обработки. Ни одна такая подпись сама по себе не подтверждает завершённый расчёт баланса компании. Признак files_available дополнительно проверяет наличие сохранённых файлов и действующий срок скачивания; у ожидающей операции файлов ещё может не быть.

Тарификация по изображениям может принять согласованный отчёт только с общими токенами, не выдавая его за детализацию по модальностям. Ответ помечает его как usage.token_usage_status=aggregate_only_not_priced и помещает полученные итоги в usage.reported_tokens. Отсутствующий cached_tokens неизвестен, а не равен нулю. Токенный тариф по-прежнему требует необходимой детализации. При review_required или более точной ошибке usage поставщика сохраните ID операции и обратитесь в поддержку вместо нового платного запроса компании.

Обычные ответы ожидающих и выполняющихся операций не содержат расчётных и пустых полей. Читайте операцию с ?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 автоматически после тайм-аута или неоднозначной ошибки. Проверьте статус операции и сохраните исходный ключ идемпотентности. Подробные внутренние ошибки конфигурации и учётных данных клиенту не возвращаются.