Generate Images

POST /images/generations

Generate Images

cURL

curl --request POST \
  --url https://api.example.com/images/generations

import requests

url = "https://api.example.com/images/generations"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/images/generations"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/images/generations")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

200

{
  "created": 123,
  "data": [
    {
      "url": "<string>",
      "b64_json": "<string>",
      "revised_prompt": "<string>"
    }
  ],
  "usage": {}
}

Creates an image given a prompt.

Method Signature

client.images.generate(
    prompt="A cute cat",
    model="dall-e-3",
    size="1024x1024",
    quality="hd",
    n=1,
    response_format="url",
    style="vivid"
)

Parameters

prompt · string · required

A text description of the desired image(s). The maximum length is:

• 32000 characters for GPT image models
• 4000 characters for dall-e-3
• 1000 characters for dall-e-2

model · string

The model to use for image generation. Options:

• dall-e-2
• dall-e-3
• gpt-image-1
• gpt-image-1-mini
• gpt-image-1.5
• chatgpt-image-latest

Defaults to dall-e-2 unless a parameter specific to the GPT image models is used.

n · integer

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

quality · string

The quality of the image that will be generated:

• auto (default) - automatically select the best quality for the given model
• high, medium, low - supported for GPT image models
• hd, standard - supported for dall-e-3
• standard - only option for dall-e-2

response_format · string

The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated.

This parameter is only supported for dall-e-2 and dall-e-3 - GPT image models always return base64-encoded images.

size · string

The size of the generated images:

• GPT image models: 1024x1024, 1536x1024 (landscape), 1024x1536 (portrait), or auto (default)
• dall-e-2: 256x256, 512x512, or 1024x1024
• dall-e-3: 1024x1024, 1792x1024, or 1024x1792

style · string

The style of the generated images. Only supported for dall-e-3:

• vivid - generates hyper-real and dramatic images
• natural - produces more natural, less hyper-real looking images

background · string

Allows to set transparency for the background of the generated image(s). Only supported for GPT image models:

• transparent
• opaque
• auto (default) - model automatically determines the best background

If transparent, the output format needs to support transparency (png or webp).

output_format · string

The format in which the generated images are returned. Only supported for GPT image models:

• png (default)
• jpeg
• webp

output_compression · integer

The compression level (0-100%) for the generated images. Only supported for GPT image models with webp or jpeg output formats. Defaults to 100.

moderation · string

Control the content-moderation level for images generated by the GPT image models:

• auto (default)
• low - less restrictive filtering

stream · boolean

Generate the image in streaming mode. Defaults to false. Only supported for GPT image models. See the Image generation guide for more information.

partial_images · integer

The number of partial images to generate. Used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event.

Note that the final image may be sent before the full number of partial images are generated if the full image is generated more quickly.

user · string

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Returns

Returns an ImagesResponse object containing the generated images.

created · integer

The Unix timestamp (in seconds) of when the image was created.

data · array

The list of generated images.

Show Image object

url · string

The URL of the generated image (for dall-e-2 and dall-e-3 with response_format=url). URLs are only valid for 60 minutes.

b64_json · string

The base64-encoded JSON of the generated image. Returned by default for GPT image models, or when response_format=b64_json for DALL-E models.

revised_prompt · string

For dall-e-3 only, the revised prompt that was used to generate the image.

usage · object

For gpt-image-1 only, the token usage information for the image generation.

Examples

Generate with DALL-E 3 (URL response)

from openai import OpenAI
client = OpenAI()

response = client.images.generate(
    model="dall-e-3",
    prompt="A futuristic cityscape at sunset",
    size="1024x1024",
    quality="hd",
    n=1
)

image_url = response.data[0].url
print(f"Image URL: {image_url}")

Generate with DALL-E 2 (base64 response)

import base64
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="dall-e-2",
    prompt="A white siamese cat",
    size="512x512",
    response_format="b64_json",
    n=2
)

for i, image in enumerate(response.data):
    image_data = base64.b64decode(image.b64_json)
    with open(f"image_{i}.png", "wb") as f:
        f.write(image_data)

Generate with GPT Image model

from openai import OpenAI
client = OpenAI()

response = client.images.generate(
    model="gpt-image-1.5",
    prompt="A minimalist logo design for a tech startup",
    size="1024x1024",
    quality="high",
    background="transparent",
    output_format="png"
)

# GPT image models always return base64
import base64
image_data = base64.b64decode(response.data[0].b64_json)
with open("logo.png", "wb") as f:
    f.write(image_data)

Streaming generation

from openai import OpenAI
client = OpenAI()

stream = client.images.generate(
    model="gpt-image-1",
    prompt="A scenic mountain landscape",
    stream=True,
    partial_images=2
)

for event in stream:
    if event.type == "partial_image":
        print(f"Received partial image at {event.partial_image.progress}% progress")
    elif event.type == "completed":
        print("Image generation completed!")
        image_data = event.data[0].b64_json