Генерация изображений API Интеграция: OpenAI-совместимые шаблоны

Интеграция создания образа API — это практика вызова конечной точки стабильного образа — обычно POST /v1/images/generations и часто POST /v1/images/edits — из кода продукта, сохраняя при этом выбор модели, учетные данные, квоты и хранилище мультимедиа за пределами каждого клиента. В шлюзе, совместимом с OpenAI, приложения отправляют приглашение и дополнительные поля model, n, size, quality и GPT Image, такие как output_format, а затем декодируют полезные данные base64 (или обрабатывают устаревшие ответы URL-адресов). только если модель все еще их поддерживает). В этом руководстве показан производственный путь интеграции с использованием шлюзовых маршрутов, которые уже предоставляет этот репозиторий, без придумывания цен поставщиков или показателей качества.

Минимально правильная форма для GPT Image

Используйте один аутентифицированный базовый URL-адрес, один токен носителя, выданный вашим шлюзом, и текущий контракт OpenAI GPT Image. В официальных документах в качестве текущей модели основного изображения указан gpt-image-2; Поколения GPT Image возвращают data[].b64_json. Параметр response_format применяется к устаревшим моделям DALL·E, а не к GPT Image.

curl -sS https://YOUR_GATEWAY/v1/images/generations \
  -H "Authorization: Bearer $GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A product photo of a ceramic mug on a wooden table, soft window light",
    "n": 1,
    "size": "1024x1024",
    "output_format": "png"
  }' | jq -r '.data[0].b64_json' | base64 --decode > mug.png

Рассматривайте ответ как эфемерный носитель плюс метаданные о выставлении счетов, а не как долгосрочный продукт. Если вашему продукту требуются изображения после истечения срока действия URL-адреса временного поставщика (устаревшие модели или адаптеры, отличные от OpenAI), немедленно загрузите их в объектное хранилище, которым вы управляете, или используйте личный путь сохранения рабочей среды изображений, который шлюз авторизует владельцем пользователя.

Всегда перепроверяйте поля, специфичные для модели, в текущих Руководство по созданию изображений OpenAI и Ссылка Images API. Google документирует генерацию изображений Gemini отдельно на ai.google.dev. Шлюз не заменяет эти документы — он нормализует доступ.

Зачем интегрировать через шлюз вместо множества SDK

Продуктовые команды обычно не справляются с интеграцией изображений по эксплуатационным причинам, а не по качеству модели:

• каждая служба имеет свой ключ поставщика
• быстрые эксперименты в обход бюджетов
• временные URL-адреса CDN сохраняются в базах данных и позже ломаются.
• изображение n или разрешение умножает стоимость без проверки
• личные песочницы и командные проекты имеют один ключ, поэтому атрибуция затрат невозможна.

Шаблон шлюза с несколькими поставщиками, более широко описанный в мультипровайдерский шлюз LLM и OpenAI-совместимый шлюз API, обеспечивает стабильность клиентов, в то время как операторы сопоставляют стабильные псевдонимы с каналами, обеспечивают соблюдение квот и ведут журналы использования. Для мультимедиа та же плоскость управления также должна ответить на вопрос: «Кто может загрузить этот ресурс позже?»

Конечные точки и поля запроса, которые имеют значение

Поколения

POST /v1/images/generations — это точка входа для преобразования текста в изображение. Поля, которые обычно появляются в DTO запроса изображения этого репозитория, включают:

Поле	Роль на GPT Image/шлюзе
model	Предпочитайте стабильный псевдоним gpt-image-2 (или сопоставленный псевдоним); более старые идентификаторы gpt-image-1* находятся на пути прекращения поддержки OpenAI в сторону gpt-image-2.
prompt	необходимая текстовая инструкция
n	необязательный подсчет; тип указателя сохраняет присутствие JSON, но этот шлюз нормализует n=0 (или опускается) до 1 перед выставлением счета
size	строка разрешения, такая как 1024x1024, 1536x1024, 1024x1536; GPT Image 2 также документирует более широкие правила WIDTHxHEIGHT.
quality	токен качества, зависящий от поставщика, если он поддерживается
output_format	png / jpeg / webp для семейств GPT Image
output_compression	сжатие для форматов, которые его поддерживают
response_format	только устаревшие версии DALL·E (url или b64_json); не поддерживается для GPT Image, который всегда возвращает base64
background, moderation, stream	расширения семейства моделей, если адаптер их поддерживает
user	тег конечного пользователя для отслеживания злоупотреблений

Не думайте, что каждое поле работает на каждой модели. Проверьте соответствие моделей, фактически включенных в вашей среде, и текущей документации поставщика.

Правки

POST /v1/images/edits — это поверхность редактирования/зарисовки. Интеграции обычно отправляют составные поля формы для исходного изображения, дополнительной маски и приглашения. Код продукта должен:

1. принимать пользовательские загрузки во временное хранилище с ограниченным размером
2. нормализовать типы MIME перед вызовом шлюза
3. сохранить того же владельца аутентификации и выставления счетов, что и поколения
4. никогда не записывайте необработанные байты изображения в журналы приложений

Если вашему продукту требуется только «регенерация с более быстрыми темпами», одних поколений может быть достаточно. Добавляйте изменения, когда пользователи должны сохранить состав или активы бренда.

Безопасность биллинга — часть интеграции

Генерация изображений — это API с большим количеством множителей. Враждебный клиент или клиент с ошибками, который устанавливает для n абсурдное значение, может превратить один запрос HTTP в катастрофу бухгалтерского учета. В этой кодовой базе:

• проверка запроса отклоняет n выше MaxImageN (128) перед математическими расчетами квоты
• n отсутствует или 0 нормализуется до 1 (поэтому «сохранять присутствие указателя» — это не то же самое, что «соблюдать нулевые изображения»)
• пути предварительного потребления и урегулирования по-прежнему должны отказываться от отрицательных или насыщенных зарядов
• Соотношения качество/размер становятся множителями только после проверки

Правила продукта:

• Пользовательский интерфейс по умолчанию от n до 1
• никогда не принимайте предоставленный пользователем n без верхнего зажима ниже максимальной платформы.
• показать ориентировочную стоимость перед многовариантной генерацией
• если предварительное потребление не удалось, провалите UX; не стоит «оптимистично стоять в очереди» к другому кошельку

TypeScript: генерировать, декодировать, сохранять

type ImageGenResponse = {
  data: Array<{ b64_json?: string; url?: string; revised_prompt?: string }>;
};

async function generatePng(prompt: string, model = "gpt-image-2") {
  const res = await fetch(`${process.env.GATEWAY_BASE}/v1/images/generations`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GATEWAY_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model,
      prompt,
      n: 1,
      size: "1024x1024",
      output_format: "png",
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  const body = (await res.json()) as ImageGenResponse;
  const b64 = body.data?.[0]?.b64_json;
  if (!b64) {
    // Legacy/provider-adapter path only: some non-GPT models may still return url.
    if (body.data?.[0]?.url) {
      return { kind: "url" as const, url: body.data[0].url, revised: body.data[0].revised_prompt };
    }
    throw new Error("no image payload");
  }
  const bytes = Buffer.from(b64, "base64");
  // upload bytes to object storage under the billing owner's key prefix
  return { kind: "bytes" as const, bytes, revised: body.data[0].revised_prompt };
}

Python: тот же контракт с явным декодированием.

import base64
import os
from pathlib import Path
import requests

def generate_and_store(prompt: str, model: str = "gpt-image-2") -> Path:
    r = requests.post(
        f"{os.environ['GATEWAY_BASE']}/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['GATEWAY_KEY']}"},
        json={
            "model": model,
            "prompt": prompt,
            "n": 1,
            "size": "1024x1024",
            "output_format": "webp",
            "output_compression": 80,
        },
        timeout=120,
    )
    r.raise_for_status()
    b64 = r.json()["data"][0]["b64_json"]
    out = Path("/tmp/out.webp")
    out.write_bytes(base64.b64decode(b64))
    return out

Предпочитайте b64_json (GPT Image по умолчанию), если вы управляете хранилищем и хотите совершить одно путешествие туда и обратно. Упоминайте url только как поведение устаревшей модели или адаптера поставщика. Никогда не предполагайте, что URL-адрес остается действительным бесконечно.

Рабочая среда для личных изображений и рабочая среда для командного видео

Этот репозиторий предоставляет рабочую среду изображений с личной областью/сессией/токеном:

• Пользовательский интерфейс: рабочий стол для изображений
• Пользовательские API под /api/user/image-workbench/* (предустановки, шаблоны, прогоны, ресурсы, создание, редактирование)
• Варианты ключа API под /api/image-workbench/* для создания/редактирования/загрузки
• Инструменты шаблона администратора под /api/image-workbench/admin/*
• Ключи объекта и история использования владения пользователя

В текущем дереве нет маршрутов /api/teams/:team_id/image-workbench с областью действия команды. Не заявляйте права на историю изображений команды или ресурсы изображений на уровне проекта, если только ваша вилка не добавит их.

Напротив, видео верстак включает маршруты команды/проекта в /api/teams/:team_id/video-workbench. Если менеджеры по продукту просят «общую историю изображений, например, видео», это является пробелом в функции, а не тем, что уже обеспечивает текущая среда обработки изображений. Мультитенантное выставление счетов за необработанный /v1/images/* по-прежнему следует за владельцем выставления счетов токена; см. мультитенантная архитектура шлюза LLM.

Используйте рабочую среду, когда операторам или дизайнерам нужна интерактивная история и настройки. Используйте необработанный /v1/images/*, когда серверные службы генерируют ресурсы программным способом. Оба пути должны использовать одни и те же псевдонимы модели и поля журнала использования для последующей атрибуции.

Контрольный список жизненного цикла носителя

1. Отправить с помощью ключа шлюза с заданной областью действия, а не ключа поставщика.
2. Проверьте n (помните, что 0 здесь становится 1), размер и длину запроса перед отправкой.
3. Запишите идентификатор запроса/идентификатор журнала использования для поддержки.
4. Раскодируйте b64_json (или один раз получите устаревший URL-адрес) и сохраните ключи хранилища объектов в соответствии с вашей политикой хранения.
5. Разрешить последующие загрузки по владельцу (пользователь для ресурсов рабочей среды изображений; владелец выставления счетов для заданий API, которые вы сохраняете самостоятельно).
6. Увеличьте срок действия или повторно модерируйте ресурсы, если этого требует политика продукта.
7. Наблюдайте частоту отказов и стоимость по моделям с помощью стека мониторинга.

Если шаг 4 пропущен, ошибки продукта появятся через несколько недель в виде неработающих миниатюр, а не ошибок API.

Подсказки и технические примечания к продукту

• Отделите намерение системы (правила бренда) от подсказки пользователю на уровне приложения; Изображения API обычно представляют собой одну строку prompt, поэтому составляйте их осторожно.
• Сохраните отправленное вами окончательное приглашение, а не только черновик пользовательского интерфейса, поскольку поставщики могут вернуть revised_prompt.
• Ограничить количество одновременных заданий изображения на пользователя; Конечные точки изображения легко случайно разойтись при повторных попытках.
• Сопоставьте HTTP 429/5xx с ограниченными повторами и идемпотентными ключами клиента там, где их поддерживает ваш стек (LLM API повторные попытки и идемпотентность).
• Для экспериментов с несколькими моделями меняйте только псевдоним model после проверки поддержки размера/качества — не делайте форк всего клиента.
• Предпочитайте gpt-image-2 в качестве примера по умолчанию; явно отображать старые псевдонимы, если канал все еще предоставляет их.

Распространенные ошибки интеграции

Симптом	Вероятная причина	Исправить
Пустые изображения после «успеха»	Искал url на GPT Image	Прочтите b64_json и раскодируйте.
Внезапное сжигание квоты	Неограниченное n или повторные попытки	Зафиксировать n, повторные попытки дедупликации
Ожидается, что n=0 будет означать «пробный прогон».	Шлюз нормализует 0 → 1	Пропустить вызов вместо отправки нуля
В личном кабинете работает, с командным ключом не работает	В ключе отсутствует грант проекта / неправильная группа моделей	Исправить выдачу токенов команды; не предполагайте, что рабочая среда изображений является областью действия команды
Изменить конечную точку 400	Неправильные имена составных полей или размер маски.	Согласование с контрактом формы поставщика/шлюза
Модель не найдена	Псевдоним не сопоставлен с каналом	Стабильный псевдоним карты → идентификатор восходящего канала в конфигурации канала

Связанное чтение

• Генерация изображений API сравнение 2026

Источники

• Руководство по созданию изображений OpenAI
• OpenAI Images API ссылка
• Прекращение поддержки OpenAI (старая версия GPT Image → gpt-image-2)
• Генерация изображений Google Gemini
• OWASP Top 10 для приложений LLM

Вопросы и ответы о неудачах

Должен ли я вызывать OpenAI, Gemini и другие с тремя SDK?

Нет, если вашему продукту нужен только один клиентский контракт. Для генерации/редактирования отдавайте предпочтение OpenAI-совместимому пути шлюза и сохраняйте собственные SDK для функций, которые шлюз еще не отображает.

Безопасен ли response_format=url для производственных баз данных?

Это неправильное значение по умолчанию для GPT Image (не поддерживается/всегда base64). Для устаревших моделей, которые по-прежнему возвращают URL-адреса, рассматривайте URL-адрес только как временный указатель и повторно размещайте их перед долгоживущими страницами продуктов.

Каково безопасное значение по умолчанию для n?

Начните с 1 в рабочем UX. Поднимайте только там, где продукт явно нуждается в вариантах, и сохраняйте фиксированный максимум продукта ниже максимума платформы (128 в этой кодовой базе). Не отправляйте n=0, ожидая отсутствия операции.

Нужна ли потоковая передача запросов изображений?

Обычно нет. Включайте потоковую передачу только в том случае, если ваш адаптер и пользовательский интерфейс поддерживают частичный предварительный просмотр; в противном случае сохраните простой путь запроса/ответа.

Как команды делятся историей изображений, не допуская утечки ресурсов?

При использовании текущего шлюза история рабочей среды изображений является личной. Для общих библиотек создайте общий ресурс уровня приложения поверх хранящихся байтов или используйте ключи группового проекта только для выставления счетов /v1/images/*, реализуя собственный список управления доступом для постоянных объектов.

Первое подключение к производству

Подключите одно серверное задание к POST /v1/images/generations с помощью model=gpt-image-2, n=1, output_format=png, декодирования base64 и немедленной загрузки объекта в хранилище. Убедитесь, что в журнале использования указан предполагаемый владелец счетов, а затем добавьте второй псевдоним модели только после проверки совместимости размера и качества в конфигурации вашего канала.