GPT Image2 Economy Text to Image API

Description

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.

Use Cases

• 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.

Endpoint Information

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

Create Task

Request Parameters

Constraints: prompt is required; reference_image_urls supports up to 8 images; output_count supports 1-4; image_size supports 1K, 2K, and 4K.

Request Example

curl -X POST '<BASE_URL>/images/text2image' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "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

curl -X POST '<BASE_URL>/images/text2image' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "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"
  }'

Success Response

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": 1778313600,
    "status": "TASK_PENDING"
  },
  "timestamp": 1778313600
}

Query Task

Path Parameters

Request Example

curl -X GET '<BASE_URL>/images/text2image/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <API_TOKEN>'

Success Response

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TASK_SUCCEEDED",
    "image_urls": [
      "https://example.com/generated_1.png"
    ],
    "mime_types": [
      "image/png"
    ],
    "generated_count": 1,
    "partial": false
  },
  "timestamp": 1778313700
}

Notes

• We recommend using Batch Upload first to obtain stable, accessible URLs for reference images.
• When reference_image_urls is omitted, images are generated from text; when provided, the request is processed as reference-image editing.
• We recommend that prompt explicitly describe the subject, composition, background, materials, lighting, and style — avoid single-keyword prompts.
• If you need a task completion notification, pass a callback_url; otherwise, retrieve the task status via the query endpoint.

Related Documents

• API Basics
• Error Handling