How to use the DALL·E API

This notebook shows how to use OpenAI's DALL·E image API endpoints.

There are three API endpoints:

• Generations: generates an image or images based on an input caption
• Edits: edits or extends an existing image
• Variations: generates variations of an input image

Setup

• Import the packages you'll need
• Import your OpenAI API key: You can do this by running `export OPENAI_API_KEY="your API key"` in your terminal.
• Set a directory to save images to

Generations

The generation API endpoint creates an image based on a text prompt. API Reference

Required inputs:

• prompt (str): A text description of the desired image(s). The maximum length is 1000 characters for dall-e-2 and 4000 characters for dall-e-3.

Optional inputs:

• model (str): The model to use for image generation. Defaults to dall-e-2
• n (int): The number of images to generate. Must be between 1 and 10. Defaults to 1.
• quality (str): The quality of the image that will be generated. hd creates images with finer details and greater consistency across the image. This param is only supported for dall-e-3.
• response_format (str): The format in which the generated images are returned. Must be one of "url" or "b64_json". Defaults to "url".
• size (str): The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models. Defaults to "1024x1024".
• style(str | null): The style of the generated images. Must be one of vivid or natural. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. This param is only supported for dall-e-3.
• user (str): A unique identifier representing your end-user, which will help OpenAI to monitor and detect abuse. Learn more.

Variations

The variations endpoint generates new images (variations) similar to an input image. API Reference

Here we'll generate variations of the image generated above.

Required inputs:

• image (str): The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.

Optional inputs:

• model (str): The model to use for image variations. Only dall-e-2 is supported at this time.
• n (int): The number of images to generate. Must be between 1 and 10. Defaults to 1.
• size (str): The size of the generated images. Must be one of "256x256", "512x512", or "1024x1024". Smaller images are faster. Defaults to "1024x1024".
• response_format (str): The format in which the generated images are returned. Must be one of "url" or "b64_json". Defaults to "url".
• user (str): A unique identifier representing your end-user, which will help OpenAI to monitor and detect abuse. Learn more.

Edits

The edit endpoint uses DALL·E to generate a specified portion of an existing image. Three inputs are needed: the image to edit, a mask specifying the portion to be regenerated, and a prompt describing the desired image. API Reference

Required inputs:

• image (str): The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.
• prompt (str): A text description of the desired image(s). The maximum length is 1000 characters.

Optional inputs:

• mask (file): An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where image should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as image.
• model (str): The model to use for edit image. Only dall-e-2 is supported at this time.
• n (int): The number of images to generate. Must be between 1 and 10. Defaults to 1.
• size (str): The size of the generated images. Must be one of "256x256", "512x512", or "1024x1024". Smaller images are faster. Defaults to "1024x1024".
• response_format (str): The format in which the generated images are returned. Must be one of "url" or "b64_json". Defaults to "url".
• user (str): A unique identifier representing your end-user, which will help OpenAI to monitor and detect abuse. Learn more.

Set Edit Area

An edit requires a "mask" to specify which portion of the image to regenerate. Any pixel with an alpha of 0 (transparent) will be regenerated. The code below creates a 1024x1024 mask where the bottom half is transparent.

Perform Edit

Now we supply our image, caption and mask to the API to get 5 examples of edits to our image