Text to Image

GPT Image2 Economy Text to Image API

The GPT Image2 Economy Text to Image API generates images from text prompts and can also perform image editing when combined with reference images. Use prompt to describe the subject, composition, materials, lighting, and style, and use parameters such as aspect_ratio, image_size, quality, and output_count to control the output specifications. This endpoint is ideal for quickly generating design assets, product images, concept art, and social media visuals.

  • Generate product images, visual concepts, marketing images, or social media assets from text.
  • Adjust backgrounds, styles, compositions, or local details based on reference images.
  • Generate multiple candidate images in a single request for creative exploration and asset selection.

For the task status enum definitions, see API Basics. We recommend using Batch Upload first to obtain stable, accessible URLs for reference images.

Create Task

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /images/text2image
  • Method: POST
  • Request Format: application/json
  • Response Format: application/json

The full request URL consists of the base URL and the endpoint path; see API Basics.

Request Headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format.

  • Fixed value: application/json

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme.

  • Format: Bearer <API_TOKEN>
  • 【Note】There is exactly one space between Bearer and <API_TOKEN>.

Request Body

prompt

Type: string ｜ Required: Yes ｜ Default: None

Image generation or editing description, up to 10,000 characters.

  • We recommend that prompt explicitly describe the subject, composition, background, materials, lighting, and style — avoid single-keyword prompts.

reference_image_urls

Type: string[] ｜ Required: No ｜ Default: None

List of reference image URLs, up to 8 images; when provided, the request is processed as image editing.

  • When reference_image_urls is omitted, images are generated from text; when provided, the request is processed as reference-image editing.

output_count

Type: integer ｜ Required: No ｜ Default: 1

Number of output images, range 1-4.

aspect_ratio

Type: string ｜ Required: No ｜ Default: 1:1

Image aspect ratio. Default model allowed values: 1:1, 3:2, 2:3, 3:4, 4:3, 16:9, 9:16, 21:9, 9:21. When model=gemini-3.1-flash-image-preview: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1.

image_size

Type: string ｜ Required: No ｜ Default: 1K

Image size tier. Allowed values: 1K, 2K, 4K (case-insensitive).

quality

Type: string ｜ Required: No ｜ Default: low

Quality tier. Allowed values: low, medium, high.

output_mime_type

Type: string ｜ Required: No ｜ Default: image/jpeg

Output format. Allowed values: image/png, image/jpeg, image/webp.

callback_url

Type: string ｜ Required: No ｜ Default: None

Callback URL invoked when the task completes; must be an HTTP/HTTPS URL, up to 500 characters.

  • If you need a task completion notification, pass a callback_url; otherwise, retrieve the task status via the query endpoint.

Request Example

bash
Copy
curl --location --request POST '<BASE_URL>/images/text2image' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "A clean, premium product shot of a ceramic mug, white background, soft studio lighting, sharp details",
    "aspect_ratio": "16:9",
    "image_size": "2K",
    "quality": "high",
    "output_count": 1,
    "output_mime_type": "image/png"
}'

Reference-Image Editing Example

bash
Copy
curl --location --request POST '<BASE_URL>/images/text2image' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "Replace the background with a bright modern photo studio, keeping the main product unchanged",
    "reference_image_urls": [
      "https://example.com/source-product.png"
    ],
    "image_size": "2K",
    "quality": "medium",
    "output_count": 1,
    "output_mime_type": "image/png"
}'

Response Body

json
Copy
{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000", // Task ID, used to query the result
        "created_at": 1778313600,                          // Task creation time, Unix timestamp in seconds
        "status": "TASK_PENDING"                           // Task status; see "API Basics - Task Status"
    },
    "timestamp": 1778313600                                // Response time, Unix timestamp in seconds
}

task_id

Type: string

Task ID, used to query the result.

created_at

Type: number

Task creation time, Unix timestamp in seconds.

status

Type: string

Task status; see Task Status.

Query Task (Single)

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /images/text2image/{task_id}
  • Method: GET
  • Request Format: application/json
  • Response Format: application/json

Request Headers

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme.

  • Format: Bearer <API_TOKEN>
  • 【Note】There is exactly one space between Bearer and <API_TOKEN>.

Path Parameters

task_id

Type: string ｜ Required: Yes ｜ Default: None

Task ID returned by the create-task endpoint.

  • 【Note】This is a path parameter; fill the value directly into the request path. Its value is the task_id returned by the create-task endpoint.

Request Example

bash
Copy
curl --location --request GET '<BASE_URL>/images/text2image/550e8400-e29b-41d4-a716-446655440000' \
--header 'Authorization: Bearer <API_TOKEN>'

Response Body

json
Copy
{
    "code": 200,                                           // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",  // Task ID
        "status": "TASK_SUCCEEDED",                         // Task status; see "API Basics - Task Status"
        "image_urls": [                                     // Returned on success; list of image URLs
            "https://example.com/generated_1.png"
        ],
        "mime_types": [                                     // Returned on success; list of image MIME types
            "image/png"
        ],
        "generated_count": 1,                               // Returned on success; number of images actually generated
        "partial": false                                    // Returned on success; indicates whether generation was only partially successful
    },
    "timestamp": 1778313700                                 // Response time, Unix timestamp in seconds
}

task_id

Type: string

Task ID.

status

Type: string

Task status; see Task Status.

image_urls

Type: string[]

Returned on success; list of image URLs.

mime_types

Type: string[]

Returned on success; list of image MIME types.

generated_count

Type: integer

Returned on success; number of images actually generated.

partial

Type: boolean

Returned on success; indicates whether generation was only partially successful.

Previous
Bach Video Generation
Next
Text to Subject
On this page
Text to Image | bach.art | bach.art