Изображения, видео и файлы

Создавайте изображения, видео и другие медиа через асинхронные задания. Модели, параметры и цены общие со Студией. Для поддерживаемых моделей изображений также доступны OpenAI-совместимые синхронные обработчики.

Настройки и стоимость

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

Асинхронная генерация

Сначала POST /v1/generations/quote с model, prompt, settings, inputs и при необходимости mode. Он не создаёт платное задание. Для подтверждения передайте price_mfc, catalog_release_id, quote_fingerprint в expected_quote запроса создания.

json

{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "Горный пейзаж в лучах рассвета",
  "settings": {
    "resolution": "1K",
    "aspect_ratio": "1:1",
    "quality": "low",
    "output_format": "png"
  },
  "inputs": {}
}

POST /v1/generations требует generations:write и Idempotency-Key. Новый job возвращается с HTTP201, повтор — HTTP200 и X-Idempotency-Replayed: true. ID имеет обычный RenderFox-формат RFI/RFV/RFA/RFD. GET /v1/generations/{id} возвращает queued, processing, completed, failed или cancelled, результат и FC. Неизвестный progress равен null.

В видео с несколькими режимами mode обязателен. Доступные имена, input roles и параметры берутся из /v1/models/{id}; конфликт first/last/reference отвергается сервером. Изображения с опубликованной автоматической маршрутизацией выбирают text/edit по входным файлам. Аудио и 3D из библиотеки используют тот же native generations lifecycle. Роли входов, допустимые кодеки и формат результата описаны в карточке модели.

Синхронные запросы изображений

POST /v1/images/generations и /v1/images/edits возвращают OpenAI ImagesResponse с created и data[].b64_json. Поддержаны только продукты с картой размеров output_sizes, n=1, формат ответа b64_json. size — точное WIDTHxHEIGHT из модели либо auto для её опубликованных defaults. Неизвестный размер не округляется к ближайшему. quality=auto использует опубликованный default; неподдерживаемые stream/mask/markup/compression отвергаются.

Синхронное ожидание ограничено60сек. Если job ещё выполняется, ответ504 generation_pending содержит generation_id и Location. Задача и финансовое решение сохранены. Повторите абсолютно то же тело с тем же Idempotency-Key либо получите native status; новый ключ может создать новое платное задание. Ответ202 не подменяет ImagesResponse.

Edits принимает multipart image/image[] либо JSON image с собственными file IDs. Для multipart дополнительно нужен files:write; суммарное тело ограничено20MiB, количество и типы повторно проверяются выбранным режимом. Повтор multipart сравнивает упорядоченные хеши исходных байтов, а не новые file IDs или имя файла.

Видео создаётся через POST /v1/videos. Проверяйте состояние через GET /v1/videos/{id} и скачивайте результат через /content. Принятое задание отменить нельзя: запрос отмены возвращает 409 cancellation_not_supported, а генерация продолжает выполняться.

GIF и режимы

Для GIF в GPT Image 2.6 доступны: 1K / Low / 1:1 / Auto или Opaque. Другие сочетания GIF отклоняются до создания задания.

Безопасность файлов

POST /v1/files — multipart file, purpose=generation, role из capability map. Ответ содержит file ID, MIME, bytes и срок хранения 24 часа. До 100 активных файлов общим размером 500 MiB на аккаунт и до четырёх одновременных загрузок. Общий предел загрузки — 100 MiB; типизированный image/audio/video validator может иметь меньший предел. Content-Length не считается доказательством размера: проверяются фактические байты.

GET /v1/files/{id} — metadata; /content — GET/HEAD/Range с files:read. DELETE требует files:write; файл активного job удалить нельзя. После TTL доступ прекращается; неиспользуемые оригиналы удаляются по сроку хранения. Задание сохраняет отдельную копию входов, удаление input file не удаляет историю.

Результаты доступны через защищённые GET/HEAD/Range /v1/generations/{id}/content/{index} с разрешением, с которым создано задание. Чужой ID отвечает404. MIME берётся из проверенного сохранённого результата; скачивается исходный файл, а не миниатюра. Все ответы no-store. Пользуйтесь авторизованным content endpoint; не передавайте ключ в URL. Входные файлы проверяются по MIME и содержимому.

Точная схема: OpenAPI3.1. Сверяйте настройки конкретного режима с карточкой модели и сохранённой версией quote.

Изображения: настройки и доставка

В карточке модели выберите режим и проверьте resolution, aspect_ratio, quality, background, output_format и роли входов. OpenAI Images использует точную опубликованную карту WIDTHxHEIGHT. Асинхронные задания используют settings выбранного режима. Количество и размер refs проверяются сервером; сборы за файлы входят в quote.

b64_json содержит исходный файл результата. При async доставке скачайте результат по защищённому content endpoint. Приватный результат не получает бессрочную публичную ссылку.

Видео: режимы и Range

Текст, первый/последний кадр, references и video edit — разные режимы. Укажите mode явно и передайте inputs с ролями из карточки. Нельзя совместить произвольные first_frame, last_frame и refs вне схемы режима. Настройки звука, длительности и кадра берутся из того же каталога, что и Студия.

После создания сохраняйте ID задачи. Poll с разумным интервалом, увеличивая задержку при 429; GET не создаёт новое платное задание. HEAD и Range защищённого content endpoint позволяют узнать размер и скачать часть видео. Другому владельцу возвращается 404.

Аудио и 3D

Режим audio-модели определяет текст, голос, язык, длительность и формат файла. Для преобразования или продолжения звука загрузите собственный файл с соответствующей ролью. Режим 3D определяет текст или входное изображение, texture, PBR и геометрию. Значения по умолчанию и пределы находятся в карточке.

Выдача проходит через проверку формата и кодека. Результат доступен через тот же защищённый generations content endpoint. Создание, ошибка, контентный отказ и финансовое решение сохраняются в истории.