Generate

API Reference

Images

Creates an image given a prompt

images.generate(ImageGenerateParams**kwargs) -> ImageGenerateResponse

post/images/generations

Creates a high-quality image from a text prompt using GPT-IMAGE-1, the latest image generation model with automatic prompt optimization and enhanced visual capabilities.

ParametersExpand Collapse

prompt: str

A text description of the desired image(s). GPT-IMAGE-1 supports up to 32,000 characters and provides automatic prompt optimization for best results.

minLength1

background: Optional[str]

The background setting for the image generation. GPT-IMAGE-1 supports: transparent, opaque, auto.

model: Optional[str]

The model to use for image generation. GPT-IMAGE-1 is the latest model offering the best quality with automatic optimization and enhanced capabilities.

moderation: Optional[str]

The moderation setting for the image generation. GPT-IMAGE-1 supports: low, auto.

n: Optional[int]

The number of images to generate. GPT-IMAGE-1 only supports n=1.

minimum1

output_compression: Optional[int]

The output compression for the image generation. GPT-IMAGE-1 supports: 0-100.

minimum0

output_format: Optional[str]

The output format for the image generation. GPT-IMAGE-1 supports: png, webp, jpeg.

partial_images: Optional[int]

The number of partial image chunks to return during streaming generation. This parameter is optional with a default of 0. When stream=true, this must be greater than 0 to receive progressive updates of the image as it's being generated. Higher values provide more frequent updates but may increase response overhead.

minimum0

quality: Optional[str]

The quality of the image that will be generated. GPT-IMAGE-1 supports: auto (automatically select best quality), high, medium, low.

size: Optional[str]

The size of the generated images. GPT-IMAGE-1 supports: auto (automatically select best size), 1536x1024 (landscape), 1024x1536 (portrait).

stream: Optional[Literal[false]]

If set to true, partial image data will be streamed as the image is being generated. When streaming, the response will be sent as server-sent events with partial image chunks. When stream is true, partial_images must be greater than 0.

Accepts one of the following:

false

user: Optional[str]

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

maxLength256

ReturnsExpand Collapse

class ImageGenerateResponse: …

The response from the image generation endpoint

created: int

The Unix timestamp (in seconds) of when the images were created

data: List[Data]

The list of generated images

b64_json: str

The base64-encoded JSON of the generated image. GPT-IMAGE-1 returns images in b64_json format only.

revised_prompt: Optional[str]

The optimized prompt that was used to generate the image. GPT-IMAGE-1 automatically optimizes prompts for best results.

background: Optional[str]

The background setting used for the image generation

output_format: Optional[str]

The output format of the generated image

quality: Optional[str]

The quality setting used for the image generation

size: Optional[str]

The size of the generated image

usage: Optional[Usage]

Usage statistics for the image generation request

input_tokens: int

Number of tokens in the input prompt

total_tokens: int

Total number of tokens used (input + output)

input_tokens_details: Optional[UsageInputTokensDetails]

Detailed breakdown of input tokens

text_tokens: Optional[int]

Number of text tokens in the input

output_tokens: Optional[int]

Number of tokens in the generated output

Creates an image given a prompt

python

• http
• typescript
• python

from gradient import Gradient

client = Gradient(
    access_token="My Access Token",
)
response = client.images.generate(
    prompt="A cute baby sea otter floating on its back in calm blue water",
)
print(response.created)

200 example

{
  "created": 1677649456,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEX...",
      "revised_prompt": "A cute baby sea otter floating on its back in calm blue water, captured with professional photography lighting and composition"
    }
  ],
  "background": "opaque",
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 12,
    "total_tokens": 4172,
    "input_tokens_details": {
      "text_tokens": 12
    },
    "output_tokens": 4160
  }
}

Returns Examples

200 example

{
  "created": 1677649456,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEX...",
      "revised_prompt": "A cute baby sea otter floating on its back in calm blue water, captured with professional photography lighting and composition"
    }
  ],
  "background": "opaque",
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 12,
    "total_tokens": 4172,
    "input_tokens_details": {
      "text_tokens": 12
    },
    "output_tokens": 4160
  }
}