Documentation Index
Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
Use this file to discover all available pages before exploring further.
OpenAI Images Generations API в настоящее время поддерживает несколько моделей генерации изображений, включая классическую dall-e-3, модель с улучшенными возможностями рендеринга текста gpt-image-1, новейшее поколение gpt-image-2, а также серию моделей nano-banana / nano-banana-2 / nano-banana-pro, подключенных через тот же интерфейс. Все они способны создавать высококачественные изображения на основе текстовых описаний.
В этом документе описан процесс использования OpenAI Images Generations API, который позволяет легко применять возможности генерации изображений серии OpenAI.
Процесс подачи заявки
Для использования OpenAI Images Generations API сначала перейдите на страницу OpenAI Images Generations API и нажмите кнопку «Acquire», чтобы получить необходимые для запросов креденшелы:
Если вы не вошли в систему или не зарегистрированы, произойдет автоматический переход на страницу входа, где вы сможете зарегистрироваться и войти. После входа вы автоматически вернетесь на текущую страницу.
При первом запросе предоставляется бесплатный лимит для использования API.
Модель GPT-Image-2
gpt-image-2 — новая модель генерации изображений от OpenAI, которая по сравнению с dall-e-3 и gpt-image-1 имеет следующие улучшения:
- Лучшее следование инструкциям: точное понимание сложных структурных указаний, таких как композиция, подсчет объектов, позиционные отношения.
- Четкое рендеринг текста: английские слова и цифры на постерах, меню, инфографике и логотипах практически не искажаются.
- Более богатое стилевое исполнение: нативная поддержка различных стилей, включая кинематографичные портреты, винтажные постеры, детские иллюстрации, продуктовую фотографию, инфографику.
- Поддержка нескольких соотношений и высоких разрешений: 5 соотношений сторон (1:1, 4:3, 3:4, 16:9, 9:16) и 3 уровня разрешения (1K / 2K / 4K).
Вызов API идентичен другим моделям, достаточно указать поле model со значением gpt-image-2. В ответе поле url содержит постоянную ссылку на изображение, размещённое на platform.cdn.xhuoapi.ai, которую можно открыть в браузере или встроить на веб-страницу.
Поддерживаемые значения size и уровни тарификации
gpt-image-2 проверяет только формат size: если значение не auto и не пустое, оно должно соответствовать формату WIDTHxHEIGHT (например, 1024x1024, 2048x1152, 800x600); любые другие форматы приведут к ошибке 400. Тарификация делится на два уровня:
- 1K стандартная цена: входное значение — любое из рекомендованных 1K размеров из таблицы ниже или распространённые 1K псевдонимы (
1254x1254, 1672x941, 941x1672 — это фактические размеры, которые возвращает upstream, повторное использование не повлечёт повышение цены).
- Другие размеры (1.5×): любые размеры, не входящие в 1K набор, включая рекомендованные 2K / 4K предустановки и любые пользовательские
WIDTHxHEIGHT.
Ограничения upstream для пользовательских размеров: ширина и высота кратны 16, максимальная длинная сторона ≤ 3840, общее количество пикселей ≤ 8,294,400. Превышение приведёт к отказу с ошибкой 4xx.
| Соотношение | 1K (стандарт) | 2K рекоменд. (×1.5) | 4K рекоменд. (×1.5) |
|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 4:3 | 1536x1024 | 2048x1536 | 3264x2448 |
| 3:4 | 1024x1536 | 1536x2048 | 2448x3264 |
| 16:9 | 1792x1024 | 2048x1152 | 3840x2160 |
| 9:16 | 1024x1792 | 1152x2048 | 2160x3840 |
Вы также можете передать size: "auto" или пропустить поле size, тогда модель выберет размер по умолчанию, и тарификация будет по 1K стандарту.
При 1K тарифе upstream не гарантирует точное соответствие пикселям — например, при передаче 1024x1024 может быть возвращено 1254x1254 с сохранением пропорций. Если вы повторно передадите полученный размер, тарификация останется 1K.
Вызов с 4K обычно занимает 4–8 минут, рекомендуется использовать асинхронный callback_url (см. ниже).
О параметре n
В gpt-image-2 не поддерживается n > 1: параметр игнорируется, независимо от значения n возвращается только 1 изображение и тарифицируется как одно. Для получения нескольких вариантов нужно запускать несколько параллельных запросов с разными prompt или seed, иначе изображения будут похожи. Это ограничение также действует для gpt-image-1 / gpt-image-1.5 и серии nano-banana. Модель dall-e-2 — единственная, нативно поддерживающая n > 1; dall-e-3 поддерживает только n = 1.
Ниже приведены реальные примеры, демонстрирующие возможности gpt-image-2.
Сценарий 1: Кинематографичный портрет
В подсказках можно использовать кинотермины (35mm пленка, малая глубина резкости, неоновый свет и т.п.) для точного управления атмосферой и текстурой.
Пример вызова на Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "gpt-image-2",
"prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
"size": "1024x1536"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Пример ответа:
{
"success": true,
"task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3",
"created": 1777048800,
"data": [
{
"revised_prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
"url": "https://platform.cdn.xhuoapi.ai/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png"
}
]
}
Сгенерированное изображение:

Сценарий 2: Винтажный туристический постер (с рендерингом текста)
gpt-image-2 стабильно работает с типографикой и шрифтами, идеально подходит для создания постеров, меню, открыток с текстом.
payload = {
"model": "gpt-image-2",
"prompt": "A vintage travel poster of the Amalfi Coast, Italy. Stylized art-deco illustration of cliffside lemon-yellow houses cascading down to a turquoise sea, with a small white sailboat in the harbor. Bold typography at the top reads AMALFI and at the bottom ITALIA 1958. Limited color palette: cream, sea-blue, lemon yellow, terracotta. Slight paper-grain texture.",
"size": "1024x1536"
}
Изображение по ссылке из поля url:

Модель точно воспроизвела визуальный стиль Art Deco, заголовки AMALFI и ITALIA 1958 четко и корректно отрисованы.
Сценарий 3: Сложная композиция и подсчет
Подсказка проверяет способность модели следовать структурированным инструкциям о количестве и расположении объектов.
payload = {
"model": "gpt-image-2",
"prompt": "A wooden bookshelf consisting of three shelves: On the top shelf, there should be one book. On the second shelf, there should be three books. On the bottom shelf, there should be seven books. Soft warm lighting, photorealistic, cozy library atmosphere.",
"size": "1024x1024"
}
Сгенерированное изображение:

Количество книг на трёх полках (1 / 3 / 7) полностью соответствует подсказке — это сложно стабильно получить в эпоху dall-e-3.
Сценарий 4: Иллюстративный стиль (горизонтальный формат)
Указание художественных материалов и настроения помогает получить стилизованные иллюстрации.
payload = {
"model": "gpt-image-2",
"prompt": "A soft, poetic children's book illustration of a small fox reading a book under a glowing mushroom in a moonlit forest. Watercolor and pencil texture, gentle pastel colors, dreamy atmosphere, hand-drawn feel.",
"size": "1536x1024"
}
Сгенерированное горизонтальное изображение:
Асинхронность и обратные вызовы
Вызов gpt-image-2 обычно занимает 60–90 секунд. Если не хочется держать открытым соединение, можно использовать механизм асинхронного обратного вызова через callback_url, процесс вызова идентичен другим моделям.
Серия моделей Nano Banana
Серия nano-banana основана на модели Gemini и подключена через тот же интерфейс /openai/images/generations. Для использования достаточно указать в поле model любое из значений из таблицы ниже.
| Модель | Стоимость (кредиты за вызов) | Сценарии использования |
|---|
nano-banana | 0.14 | Обычная генерация изображений, самая быстрая и дешевая |
nano-banana-2 | 0.28 | Значительно улучшенное качество и детализация |
nano-banana-pro | 0.35 | Флагман серии, лучшая композиция, детали и рендеринг текста |
Важно: поддерживаемые параметры
Nano Banana адаптирован под протокол OpenAI и поддерживает только параметры: model, prompt, size.
size маппится на внутренний aspect_ratio по таблице; неуказанные размеры по умолчанию 1:1:
1024x1024 / 512x512 / 256x256 → 1:1
1792x1024 → 16:9
1024x1792 → 9:16
- Не поддерживаются параметры
n, quality, style, response_format, background, output_format — они игнорируются.
- Возвращаемая структура соответствует формату OpenAI (
data[].url), но поле created всегда 0, b64_json не возвращается, revised_prompt всегда совпадает с исходным prompt.
Базовый вызов
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "nano-banana",
"prompt": "a small red apple on a white table, photoreal",
"size": "1024x1024"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Пример ответа:
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png",
"revised_prompt": "a small red apple on a white table, photoreal"
}
]
}
Сгенерированное изображение доступно по ссылке из поля url:

Обновление до флагманской модели nano-banana-pro
Достаточно изменить model на nano-banana-pro, остальные параметры остаются без изменений:
payload = {
"model": "nano-banana-pro",
"prompt": "abstract painting",
"size": "1024x1024"
}
Пример ответа:
{
"created": 0,
"data": [
{
"url": "https://platform.cdn.xhuoapi.ai/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png",
"revised_prompt": "abstract painting"
}
]
}

Асинхронный обратный вызов
Механизм callback_url работает и с nano-banana, процесс вызова идентичен другим моделям, см. раздел Асинхронный обратный вызов.
Базовое использование
Далее можно заполнить соответствующие поля в интерфейсе, как показано на скриншоте:

При первом использовании API необходимо заполнить минимум три поля: authorization — выбирается из выпадающего списка, model — выбирается модель OpenAI DALL-E, подробности о моделях приведены выше, и prompt — текст подсказки для генерации изображения.
Справа отображается сгенерированный код вызова, который можно скопировать и запустить, либо нажать кнопку «Try» для теста.

Пример вызова на Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Пример ответа:
{
"created": 1721626477,
"data": [
{
"revised_prompt": "A delightful image showcasing a young sea otter, who is born brown, with wide charming eyes. It is delightfully lying on its back, paddling in the calm sea waters. Its dense, velvety fur appears wet and shimmering, capturing the essence of its habitat. The small creature curiously plays with a sea shell with its small paws, looking absolutely innocent and charming in its natural environment.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/5d98aa7c-80c6-4523-b571-fc606ad455b9/generated_00.png?se=2024-07-23T05%3A34%3A48Z&sig=GAz%2Bi3%2BkHOQwAMhxcv22tBM%2FaexrxPgT9V0DbNrL4ik%3D&ske=2024-07-23T08%3A41%3A10Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T08%3A41%3A10Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Пояснения к полям ответа:
created — ID задачи генерации изображения, уникальный идентификатор.
data — содержит информацию о сгенерированном изображении.
В data находится конкретная информация о сгенерированном изображении, поле url содержит ссылку на изображение.

Параметр качества изображения quality
Далее рассмотрим, как задать параметры качества изображения. Параметр quality имеет два значения: standard — стандартное качество, и hd — более детализированное и согласованное изображение.
Пример установки параметра качества в standard:

Справа отображается сгенерированный код вызова, который можно скопировать или протестировать кнопкой «Try».

Пример вызова на Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"quality": "standard"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Пример ответа:
{
"created": 1721636023,
"data": [
{
"revised_prompt": "A cute baby sea otter is lying playfully on its back in the water, with its fur looking glossy and soft. One of its tiny paws is reaching out curiously, and it has an expression of pure joy and warmth on its face as it looks up to the sky. Its body is surrounded by bubbles from its playful twirling in the water. A gentle breeze is playing with its fur making it look more charming. The scene portrays the tranquility and charm of marine life.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/a93ee5e7-3abd-4923-8d79-dc9ef126da46/generated_00.png?se=2024-07-23T08%3A13%3A55Z&sig=wTXGYvUOwUIkaB2CxjK9ww%2FHjS8OwYUWcYInXYKwcAM%3D&ske=2024-07-23T11%3A32%3A05Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T11%3A32%3A05Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Изображение с параметром качества standard:

Аналогично, установив quality в hd, получаем изображение с более детализированными и согласованными деталями:

Параметр размера изображения size
Также можно задать размер генерируемого изображения.
Пример установки размера 1024x1024:

Справа отображается сгенерированный код вызова, который можно скопировать или протестировать кнопкой «Try».

Пример вызова на Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"size": "1024x1024"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Пример ответа:
{
"created": 1721636652,
"data": [
{
"revised_prompt": "A delightful depiction of a baby sea otter. The small mammal is captured in its natural habitat in the ocean, floating on its back. It has thick brown fur that is sleek and wet from the sea water. Its eyes are closed as if it is enjoying a moment of deep relaxation. The water around it is calm, reflecting the peacefulness of the scene. The background should hint at a diverse marine ecosystem, with visible strands of kelp floating on the surface, suggesting the baby otter's preferred environment.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/9d625ac6-fd2b-42a9-84a6-8c99eb357ccf/generated_00.png?se=2024-07-23T08%3A24%3A24Z&sig=AXtYXowEakGxfRp8LhC2DwqL%2F07LhEDW40oCP%2BdTO8s%3D&ske=2024-07-23T18%3A00%3A45Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T18%3A00%3A45Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Изображение с размером 1024x1024:

Аналогично, размер 1792x1024 даёт изображение с другим соотношением:
Можно задавать и другие размеры, подробности см. в документации на сайте.
Параметр стиля изображения style
Параметр style имеет два значения: vivid — более яркое и живое изображение, и natural — более естественное.
Пример установки style в vivid:

Справа отображается сгенерированный код вызова, который можно скопировать или протестировать кнопкой «Try».

Пример вызова на Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"style": "vivid"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Пример ответа:
{
"created": 1721637086,
"data": [
{
"revised_prompt": "A baby sea otter with soft, shiny fur and sparkling eyes floating playfully on calm ocean waters. This adorable creature is trippingly frolicking amidst small, gentle waves under a bright, clear, sunny sky. The tranquility of the sea contrasts subtly with the delightful energy of this young otter. The critter gamely clings to a tiny piece of driftwood, its small paws adorably enveloping the floating object.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/6e48f701-7fd3-4356-839e-a2f6f0fe82d9/generated_00.png?se=2024-07-23T08%3A31%3A37Z&sig=4percxqTbUR1j3BQmkhvj%2FAhHzInKI%2FqiTo1MP69coI%3D&ske=2024-07-27T10%3A39%3A55Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-20T10%3A39%3A55Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Изображение с параметром стиля vivid:

Аналогично, параметр natural даёт более естественное изображение:

vivid даёт более живую и насыщенную картинку по сравнению с natural.
Параметр response_format имеет два варианта: b64_json — ссылка на изображение в Base64-кодировке, и url — обычная ссылка на изображение.
Пример установки response_format в url:

Справа отображается сгенерированный код вызова, который можно скопировать или протестировать кнопкой «Try».

Пример вызова на Python:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"response_format": "url"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Пример ответа:
{
"created": 1721637575,
"data": [
{
"revised_prompt": "A charming depiction of a baby sea otter. The otter is seen resting serenely on its back amidst the gentle, blue ocean waves. The baby otter's fur is an endearing mix of soft greyish brown shades, glinting subtly in the muted sunlight. Its small paws are touching, lifted slightly towards the sky as if playing with an unseen object. Its round, expressive eyes are wide in curiosity, sparking with life and innocence. Use a realistic style to evoke the otter's natural habitat and its adorably fluffy exterior.",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D&ske=2024-07-23T13%3A32%3A13Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T13%3A32%3A13Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
}
]
}
Ссылка из поля url доступна для прямого просмотра: ссылка на изображение

Аналогично, при установке response_format в b64_json возвращается Base64-кодированное изображение:
{
"created": 1721638071,
"data": [
{
"b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==",
"revised_prompt": "A charming image of a young baby sea otter. The otter is gently floating on a calm blue sea, basking in the warm, golden rays of sunlight streaming down from a clear sky above. The otter's fur is a rich chocolate brown, and it looks incredibly soft and fluffy. The otter's eyes are bright and expressive, filled with childlike curiosity and joy. It has small, pricked ears and a button-like nose which adds to its overall cuteness. In the sea around it, twinkling droplets of water can be seen, pepped up by the sunlight, the sight is certainly a delightful one."
}
]
}
Асинхронный обратный вызов
Поскольку генерация изображений через OpenAI Images Generations API может занимать продолжительное время, при длительном отсутствии ответа HTTP-соединение остается открытым, что увеличивает нагрузку на систему. Поэтому API поддерживает асинхронный обратный вызов.
Схема работы: клиент при запросе указывает поле callback_url. API сразу возвращает ответ с полем task_id — идентификатором задачи. По завершении генерации результат отправляется POST-запросом в формате JSON на указанный callback_url, включая task_id для связывания результата с задачей.
Пример настройки:
Webhook — это HTTP-сервис, принимающий запросы. Для демонстрации можно использовать публичный сервис https://webhook.site/, где после открытия сайта вы получите уникальный URL Webhook, например:
Скопируйте URL, например https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Далее укажите callback_url в запросе:
import requests
url = "https://api.xhuoapi.ai/v1/openai/images/generations"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "dall-e-3",
"prompt": "A cute baby sea otter",
"callback_url": "https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Ответ сразу:
{
"task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
Через некоторое время в Webhook можно увидеть результат генерации:
{
"success": true,
"task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
"trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
"data": {
"created": 1721626477,
"data": [
{
"revised_prompt": "A delightful image showcasing a young sea otter...",
"url": "https://dalleprodsec.blob.core.windows.net/private/images/..."
}
]
}
}
В ответе есть поле task_id и поле data с результатом, что позволяет связать ответ с запросом.
Обработка ошибок
При ошибках API возвращает соответствующий код и сообщение. Например:
400 token_mismatched: неверный запрос, возможно, отсутствуют или некорректны параметры.
400 api_not_implemented: неверный запрос, возможно, отсутствуют или некорректны параметры.
401 invalid_token: неавторизован, неверный или отсутствующий токен.
429 too_many_requests: превышен лимит запросов.
500 api_error: внутренняя ошибка сервера.
Пример ответа с ошибкой
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
Заключение
В этом документе вы узнали, как использовать OpenAI Images Generations API для простой работы с официальной функцией генерации изображений OpenAI DALL-E. Надеемся, что этот материал поможет вам эффективно интегрировать и использовать API. Если возникнут вопросы, пожалуйста, обращайтесь в нашу техническую поддержку.