Image generation Beta
Learn how to generate or manipulate images with our DALL·E models
Learn how to generate or manipulate images with our DALL·E models
Introduction
The Images API provides three methods for interacting with images:
The Images API provides three methods for interacting with images:
- Creating images from scratch based on a text prompt
Create images from scratch based on a text prompt - Creating edits of an existing image based on a new text prompt
Create edits of an existing image based on a new text prompt - Creating variations of an existing image
Create variations of an existing image
This guide covers the basics of using these three API endpoints with useful code samples. To see them in action, check out our DALL·E preview app .
To see them in action, check out our DALL·E preview application.
The Images API is in beta. During this time the API and models will evolve based on your feedback. To ensure all users can prototype comfortably, the default rate limit is 50 images per minute. If you would like to increase your rate limit, please review this help center article . We will increase the default rate limit as we learn more about usage and capacity requirements.
The Image API is in beta. During this time, the API and models will be improved based on your feedback. To ensure easy prototyping for all users, the default rate limit is 50 images per minute. If you would like to increase the rate limit, please review this Help Center article. We will increase the default rate limit as we learn more about usage and capacity requirements.
Usage
Generations
The image generations endpoint allows you to create an original image given a text prompt. Generated images can have a size of 256x256, 512x512, or 1024x1024 pixels. Smaller sizes are faster to use. You can request the images at 1-10 times n parameter.
The image generation endpoint allows you to create a raw image given a text prompt. The resulting image can be 256x256, 512x512 or 1024x1024 pixels in size. Smaller sizes generate faster. You can request 1-10 images at a time using the n parameter.
Generate an image Generate an image
python
response = openai.Image.create(
prompt="a white siamese cat",
n=1,
size="1024x1024"
)
image_url = response['data'][0]['url']
The more detailed the description, the more likely you are to get the result that you or your end user want. You can explore the examples in the DALL·E preview app for more prompting inspiration. Here's a quick example:
the more detailed the description, the more you The more likely you are to get the results you or your end users want. You can explore the examples in the DALL·E preview application for more tip inspiration. Here's a simple example:
| PROMPT | GENERATION |
|---|---|
| a white siamese cat a white siamese cat | [External link picture transfer failed, the source site may have an anti-leeching mechanism, it is recommended to save the picture and upload it directly (img-waP75L2u-1681139040854)(…/…/…/…/…/…/workspace/vscode-project/ringyin -blog/source/images/image_generation_simple.webp)] |
| a close up, studio photographic portrait of a white siamese cat that looks curious, backlit ears | [External link picture transfer failed, the source site may have an anti-leeching mechanism, it is recommended to save the picture and upload it directly (img-qwZCiITS-1681139040855)(…/…/…/…/…/…/workspace/vscode-project/ringyin -blog/source/images/image_generation_detailed.webp)] |
Each image can be returned as either a URL or Base64 data, using the response_format parameter. URLs will expire after an hour
. URL will expire in one hour.
Edits
The image edits endpoint allows you to edit and extend an image by uploading a mask. The transparent areas of the mask indicate where the image should be edited, and the prompt should describe the full new image, not just the erased area . This endpoint can enable experiences like the editor in our DALL·E preview app .
The image editing endpoint allows you to edit and extend images by uploading masks. Transparent areas of the mask indicate where the image should be edited, hinting that the complete new image should be described, not just the erased area. This endpoint enables an editor-like experience in our DALL·E preview application.
Edit an image Edit an image
python
response = openai.Image.create_edit(
image=open("sunlit_lounge.png", "rb"),
mask=open("mask.png", "rb"),
prompt="A sunlit indoor lounge area with a pool containing a flamingo",
n=1,
size="1024x1024"
)
image_url = response['data'][0]['url']
| IMAGE | MASK | OUTPUT |
|---|---|---|
| [External link picture transfer failed, the source site may have an anti-leeching mechanism, it is recommended to save the picture and upload it directly (img-m46PJUK6-1681139040855)(…/…/…/…/…/…/workspace/vscode-project/ringyin -blog/source/images/image_edit_original.webp)] | [External link picture transfer failed, the source site may have an anti-theft link mechanism, it is recommended to save the picture and upload it directly (img-lygwKa3D-1681139040855)(…/…/…/…/…/…/workspace/vscode-project/ringyin -blog/source/images/image_edit_mask.webp)] | [External link picture transfer failed, the source site may have an anti-leeching mechanism, it is recommended to save the picture and upload it directly (img-4FQbAyuE-1681139040856)(…/…/…/…/…/…/workspace/vscode-project/ringyin -blog/source/images/image_edit_output.webp)] |
Prompt: a sunlit indoor lounge area with a pool containing a flamingo
The uploaded image and mask must both be square PNG images less than 4MB in size, and also must have the same dimensions as each other. The non-transparent areas of the mask are not used when generating the output, so they don't necessarily need to match the original image like the example above.
The uploaded image and mask must be square PNG images under 4MB and must have the same dimensions. The non-transparent areas of the mask are not used when generating the output, so they don't necessarily need to match the original image like in the example above.
Variations
The image variations endpoint allows you to generate a variation of a given image.
The image variations endpoint allows you to generate a variation of a given image.
Generate an image variation Generate an image variation
python
response = openai.Image.create_variation(
image=open("corgi_and_cat_paw.png", "rb"),
n=1,
size="1024x1024"
)
image_url = response['data'][0]['url']
| IMAGE | OUTPUT |
|---|---|
| [External link picture transfer failed, the source site may have an anti-leeching mechanism, it is recommended to save the picture and upload it directly (img-eBqVPWHA-1681139040856)(…/…/…/…/…/…/workspace/vscode-project/ringyin -blog/source/images/image_variation_original.webp)] | [External link picture transfer failed, the source site may have an anti-leeching mechanism, it is recommended to save the picture and upload it directly (img-C6B3QRO7-1681139040856)(…/…/…/…/…/…/workspace/vscode-project/ringyin -blog/source/images/image_variation_output.webp)] |
Similar to the edits endpoint, the input image must be a square PNG image less than 4MB in size.
Content moderation content moderation
Prompts and images are filtered based on our content policy , returning an error when a prompt or image is flagged. If you have any feedback on false positives or related issues, please contact us through our help center .
Prompts and images are based on our content policy Filter and return an error when a hint or image is flagged. If you have any feedback on false positives or related issues, please contact us through our Help Center.
Language-specific tips Language-specific tips
NODE.JSPYTHON
Using in-memory image data use memory image data
The Node.js examples in the guide above use the fsmodule to read image data from disk. In some cases, you may have your image data in memory instead. Here's an example API call that uses image data stored in a Node.js object Buffer:
The Node.js example in the guide above uses fsthe module to read image data from disk. In some cases, you may keep image data in memory. Here's an example API call that uses Bufferimage data stored in a Node.js object:
// This is the Buffer object that contains your image data
const buffer = [your image data];
// Set a `name` that ends with .png so that the API knows it's a PNG image
buffer.name = "image.png";
const response = await openai.createImageVariation(
buffer,
1,
"1024x1024"
);
Working with TypeScript 使用TypeScript
If you're using TypeScript, you may encounter some quirks with image file arguments. Here's an example of working around the type mismatch by explicitly casting the argument: . Here's an example of resolving type mismatches by explicitly casting arguments:
// Cast the ReadStream to `any` to appease the TypeScript compiler
const response = await openai.createImageVariation(
fs.createReadStream("image.png") as any,
1,
"1024x1024"
);
And here's a similar example for in-memory image data
:
// This is the Buffer object that contains your image data
const buffer: Buffer = [your image data];
// Cast the buffer to `any` so that we can set the `name` property
const file: any = buffer;
// Set a `name` that ends with .png so that the API knows it's a PNG image
file.name = "image.png";
const response = await openai.createImageVariation(
file,
1,
"1024x1024"
);
Error handling
API requests can potentially return errors due to invalid inputs, rate limits, or other issues. These errors can be handled with a statement try...catch, and the error details can be found in either error.responseor error.message:
API requests may return errors due to invalid inputs, rate limits, or other issues. problem and returns an error. These errors can be handled with try...catchstatements , and error details can be found in orerror.response :error.message
try {
const response = await openai.createImageVariation(
fs.createReadStream("image.png"),
1,
"1024x1024"
);
console.log(response.data.data[0].url);
} catch (error) {
if (error.response) {
console.log(error.response.status);
console.log(error.response.data);
} else {
console.log(error.message);
}
}
PYTHON
Using in-memory image data use memory image data
The Python examples in the guide above use the openfunction to read image data from disk. In some cases, you may have your image data in memory instead. Here's an example API call that uses image data stored in a object BytesIO:
Python in the guide above The example uses openthe function to read image data from disk. In some cases, you may keep image data in memory. Here's an example API call that uses image data stored in BytesIOa object :
from io import BytesIO
# This is the BytesIO object that contains your image data
byte_stream: BytesIO = [your image data]
byte_array = byte_stream.getvalue()
response = openai.Image.create_variation(
image=byte_array,
n=1,
size="1024x1024"
)
Operating on image data image data operation
It may be useful to perform operations on images before passing them to the API. Here's an example that uses PILto resize an image:
Here's an example of PILresizing :
from io import BytesIO
from PIL import Image
# Read the image file from disk and resize it
image = Image.open("image.png")
width, height = 256, 256
image = image.resize((width, height))
# Convert the image to a BytesIO object
byte_stream = BytesIO()
image.save(byte_stream, format='PNG')
byte_array = byte_stream.getvalue()
response = openai.Image.create_variation(
image=byte_array,
n=1,
size="1024x1024"
)
Error handling
API requests can potentially return errors due to invalid inputs, rate limits, or other issues. These errors can be handled with a statement try...except, and the error details can be found in e.error:
API requests may return errors due to invalid inputs, rate limits, or other issues. returns an error. These errors can be handled with try...exceptstatements , error details can e.errorbe found in:
try:
openai.Image.create_variation(
open("image.png", "rb"),
n=1,
size="1024x1024"
)
print(response['data'][0]['url'])
except openai.error.OpenAIError as e:
print(e.http_status)
print(e.error)