Skip to main content

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.

The OpenAI Images Generations API currently supports multiple image generation models, including the classic dall-e-3, the text rendering enhanced gpt-image-1, the latest generation gpt-image-2, as well as the nano-banana / nano-banana-2 / nano-banana-pro series models accessible through the same interface. All of these can generate high-quality images based on textual descriptions. This document mainly introduces the usage process of the OpenAI Images Generations API, enabling easy access to the OpenAI series image generation features.

​
Application Process

To use the OpenAI Images Generations API, first visit the OpenAI Images Generations API page and click the “Acquire” button to obtain the credentials required for requests: If you are not logged in or registered, you will be automatically redirected to the login page to register and log in. After logging in or registering, you will be automatically returned to the current page. A free quota is granted upon the first application, allowing free use of this API.

​
GPT-Image-2 Model

gpt-image-2 is a new generation image generation model launched by OpenAI. Compared to dall-e-3 and gpt-image-1, it has significant improvements in the following aspects:
  • Stronger instruction adherence: Accurately understands complex composition, counting, positional relationships, and other structured instructions.
  • Clearer text rendering: English and numbers in posters, menus, infographics, logos, etc., are almost free of errors.
  • Richer style expression: Natively supports various styles such as cinematic portraits, vintage posters, children’s illustrations, product photography, and infographics.
  • Native multi-aspect ratio + high resolution support: Covers 5 aspect ratios (1:1, 4:3, 3:4, 16:9, 9:16) with 3 resolution tiers (1K / 2K / 4K).
The calling method is exactly the same as other models; just set the model field to gpt-image-2. The returned url in the result is a permanently hosted image link on platform.cdn.xhuoapi.ai, which can be opened directly in a browser or embedded in a webpage.

​
Supported size Values and Billing Tiers

gpt-image-2 only validates the format of size. As long as it is not auto or an empty string, it must match WIDTHxHEIGHT (e.g., 1024x1024, 2048x1152, 800x600); any other format will return 400. Billing is divided into two tiers:
  • 1K Standard Price: Input matches any 1K recommended size in the table below or common 1K output aliases from upstream (1254x1254, 1672x941, 941x1672 — these are actual sizes returned upstream under the 1K tier; reusing them as size will not cause price jumps).
  • Other Tiers (1.5×): Any size not in the above 1K set, including the recommended 2K / 4K presets in the table below and any custom WIDTHxHEIGHT you provide.
Upstream hard constraints on custom sizes: both width and height must be multiples of 16, the longer side ≤ 3840, and total pixels ≤ 8,294,400. Sizes exceeding these limits will be rejected by upstream with a 4xx response.
Aspect Ratio1K (Standard Price)2K Recommended (×1.5)4K Recommended (×1.5)
1:11024x10242048x20482880x2880
4:31536x10242048x15363264x2448
3:41024x15361536x20482448x3264
16:91792x10242048x11523840x2160
9:161024x17921152x20482160x3840
You can also pass size: "auto" or omit the size field, in which case the model will select the default size itself and charge at the 1K standard price. Upstream output under the 1K tier does not guarantee strict pixel alignment — if you pass 1024x1024, you might receive 1254x1254 with the same aspect ratio. If you reuse that as size, it will still be charged at the 1K tier. 4K single calls usually take 4–8 minutes; it is recommended to use the callback_url asynchronous callback mechanism described later.
About the n parameter gpt-image-2 currently does not support n > 1: this parameter will be silently ignored. Whether you pass n=1 or n=10, only one image will be returned per request and charged as one image. If you need multiple candidate images at once, please concurrently send multiple requests (it is recommended to pass different prompt or seed values simultaneously; otherwise, the images may be very similar). This restriction also applies to gpt-image-1 / gpt-image-1.5 and the nano-banana / nano-banana-2 / nano-banana-pro series. dall-e-2 is currently the only model that natively supports n > 1; dall-e-3 only supports n = 1.
Below are several real examples from different perspectives to intuitively experience the capabilities of gpt-image-2.

​
Scenario 1: Cinematic Portrait

You can use cinematic terms in the prompt (35mm film, shallow depth of field, neon lights, etc.) to precisely control the atmosphere and texture. Python sample call code: 
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)
Returned result: 
{
  "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"
    }
  ]
}
Generated image:

​
Scenario 2: Vintage Travel Poster (with Text Rendering)

gpt-image-2 performs stably in typography and font rendering, making it very suitable for generating posters, menus, greeting cards, and other text-included designs. 
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"
}
Returned url corresponds to the following image:

The model not only accurately reproduces the Art Deco poster visual style but also clearly and correctly renders the title texts AMALFI and ITALIA 1958.

​
Scenario 3: Complex Composition and Counting

This prompt tests the model’s ability to follow structured instructions like “quantity” and “position.” 
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"
}
Generated image:

The number of books on the three shelves (1 / 3 / 7) exactly matches the prompt, which was difficult to achieve stably in the dall-e-3 era.

​
Scenario 4: Illustration Style (Landscape)

By specifying artistic media and mood keywords, you can guide the model to produce stylized illustrations. 
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"
}
Generated landscape illustration:

​
Asynchronous and Callback

gpt-image-2 single calls usually take 60–90 seconds. If you do not want to keep a long connection, you can use the callback_url asynchronous callback mechanism introduced later. The calling process is exactly the same as other models.

​
Nano Banana Series Models

The nano-banana series are image generation models based on Gemini, integrated through the same /openai/images/generations interface without switching endpoints. Just change the model to any one in the table below.
ModelBilling (Credits / call)Suitable Scenarios
nano-banana0.14General image generation, fastest speed, lowest cost
nano-banana-20.28Significant quality and detail improvement
nano-banana-pro0.35Flagship of the series, best composition, detail, and text
Important: Supported Parameters Nano Banana is adapted to the OpenAI protocol via an adapter layer and supports only the following parameters compared to gpt-image-*: model, prompt, size.
  • size is mapped to internal aspect_ratio as per the table below; unspecified sizes degrade to 1:1:
    • 1024x1024 / 512x512 / 256x256 → 1:1
    • 1792x1024 → 16:9
    • 1024x1792 → 9:16
  • Does not support n, quality, style, response_format, background, output_format, etc.; these will be ignored if provided.
  • Returns follow OpenAI format (data[].url), but created is fixed at 0, no b64_json returned, and revised_prompt always equals the original prompt.

​
Basic Call

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)
Returned result: 
{
  "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"
    }
  ]
}
Generated image can be accessed directly via the returned url:

​
Upgrade to Flagship Model nano-banana-pro

Simply change model to nano-banana-pro, with all other parameters unchanged: 
payload = {
    "model": "nano-banana-pro",
    "prompt": "abstract painting",
    "size": "1024x1024"
}
Sample return: 
{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.xhuoapi.ai/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png",
      "revised_prompt": "abstract painting"
    }
  ]
}

​
Asynchronous Callback

The callback_url asynchronous callback mechanism also applies to nano-banana; the calling process is exactly the same as other models. See the Asynchronous Callback section below.

​
Basic Usage

Next, you can fill in the corresponding content on the interface, as shown:

When using this interface for the first time, at least three fields need to be filled: one is authorization, which can be selected directly from the dropdown list; another is model, which is the OpenAI DALL-E official model category you choose to use. Here we mainly have one model; details can be seen in our provided models. The last parameter is prompt, which is the text prompt for image generation. You can also notice the corresponding generated call code on the right side, which you can copy and run directly or click the “Try” button to test.

Python sample call code: 
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)
After calling, the returned result is: 
{
  "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"
    }
  ]
}
The returned result contains multiple fields, described as follows:
  • created: the ID representing this image generation task, used to uniquely identify this task.
  • data: contains the image generation result information.
data contains the specific information of the generated image by the model; its url is the detail link of the generated image, as shown below.

​
Image Quality Parameter quality

Next, we introduce how to set detailed parameters for the image generation result. The image quality parameter quality includes two options: standard means generating a standard image, and hd means creating an image with finer details and greater consistency. Below is the setting for the image quality parameter as standard, as shown:

You can also notice the corresponding generated call code on the right, which you can copy and run directly or click the “Try” button to test.

Python sample call code: 
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)
Returned result: 
{
  "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"
    }
  ]
}
The returned result is consistent with basic usage. The generated image with quality set to standard is shown below:

Performing the same operation but setting the image quality parameter to hd yields the following image:

hd generates images with finer details and greater consistency compared to standard.

​
Image Size Parameter size

You can also set the size of the generated image. Below is the setting for image size as 1024 * 1024, as shown:

You can also notice the corresponding generated call code on the right, which you can copy and run directly or click the “Try” button to test.

Python sample call code: 
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)
Returned result: 
{
  "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"
    }
  ]
}
The returned result is consistent with basic usage. The generated image with size 1024 * 1024 is shown below:

Performing the same operation but setting the image size to 1792 * 1024 yields the following image: The image size is obviously different. You can also set more sizes; for details, refer to our official documentation.

​
Image Style Parameter style

The image style parameter style includes two options: vivid means the generated image is more vivid, and natural means the generated image is more natural. Below is the setting for the image style parameter as vivid, as shown:

You can also notice the corresponding generated call code on the right, which you can copy and run directly or click the “Try” button to test.

Python sample call code: 
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)
Returned result: 
{
  "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"
    }
  ]
}
The returned result is consistent with basic usage. The generated image with style set to vivid is shown below:

Performing the same operation but setting the image style parameter to natural yields the following image:

vivid generates images that are more vivid and lifelike compared to natural. The last parameter is the image link format response_format, which has two options: b64_json encodes the image link in Base64, and url is a normal image link that can be viewed directly. Below is the setting for the image link format parameter as url, as shown:

You can also notice the corresponding generated call code on the right, which you can copy and run directly or click the “Try” button to test.

Python sample call code: 
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)
Returned result: 
{
  "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"
    }
  ]
}
The returned result is consistent with basic usage. The generated image link with response_format set to url is Image URL and can be accessed directly. The image is shown below:

Performing the same operation but setting the image link format parameter to b64_json yields the Base64 encoded image link result, as shown below: 
{
  "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."
    }
  ]
}

​
Asynchronous Callback

Because the OpenAI Images Generations API may take a relatively long time to generate images, if the API does not respond for a long time, the HTTP request will keep the connection open, causing additional system resource consumption. Therefore, this API also supports asynchronous callbacks. The overall process is: when the client initiates a request, it additionally specifies a callback_url field. After the client sends the API request, the API immediately returns a result containing a task_id field, representing the current task ID. When the task is completed, the generated image result will be sent to the client’s specified callback_url via POST JSON, including the task_id field, so the task result can be correlated by ID. Below is an example to understand the specific operation. First, the Webhook callback is a service that can receive HTTP requests; developers should replace it with their own HTTP server URL. For demonstration, a public Webhook sample site https://webhook.site/ is used. Opening this site provides a Webhook URL, as shown: Copy this URL, which can be used as a Webhook. The example here is https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Next, set the callback_url field to the above Webhook URL and fill in the corresponding parameters, as in the following code: 
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)
Clicking run, you will immediately get a result like: 
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
After a short wait, you can observe the generated image result on the Webhook URL, as follows: 
{
  "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/..."
      }
    ]
  }
}
You can see the result contains a task_id field, and the data field includes the same image generation results as synchronous calls. The task_id field enables task correlation.

​
Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and message. For example:
  • 400 token_mismatched: Bad request, possibly due to missing or invalid parameters.
  • 400 api_not_implemented: Bad request, possibly due to missing or invalid parameters.
  • 401 invalid_token: Unauthorized, invalid or missing authorization token.
  • 429 too_many_requests: Too many requests, you have exceeded the rate limit.
  • 500 api_error: Internal server error, something went wrong on the server.

​
Error Response Example

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusion

Through this document, you have learned how to easily use the official OpenAI DALL-E image generation features via the OpenAI Images Generations API. We hope this documentation helps you better integrate and utilize this API. If you have any questions, please feel free to contact our technical support team.