Edit

Share via

Learn how to work with the DALL-E models

  • Article

OpenAI's DALL-E models generate images based on user-provided text prompts. This guide demonstrates how to use the DALL-E models and configure their options through REST API calls.

Prerequisites

Call the Image Generation APIs

The following command shows the most basic way to use DALL-E with code. If this is your first time using these models programmatically, we recommend starting with the DALL-E quickstart.

Send a POST request to:

https://<your_resource_name>.deployments/<your_deployment_name>/images/generations?api-version=<api_version>

where:

  • <your_resource_name> is the name of your Azure OpenAI resource.
  • <your_deployment_name> is the name of your DALL-E 3 model deployment.
  • <api_version> is the version of the API you want to use. For example, 2024-02-01.

Required headers:

  • Content-Type: application/json
  • api-key: <your_API_key>

Body:

The following is a sample request body. You specify a number of options, defined in later sections.

{
    "prompt": "A multi-colored umbrella on the beach, disposable camera",
    "size": "1024x1024", 
    "n": 1,
    "quality": "hd", 
    "style": "vivid"
}

Output

The output from a successful image generation API call looks like the following example. The url field contains a URL where you can download the generated image. The URL stays active for 24 hours.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "url": "<URL_to_generated_image>",
            "revised_prompt": "<prompt_that_was_used>" 
        }
    ]
}

API call rejection

Prompts and images are filtered based on our content policy, returning an error when a prompt or image is flagged.

If your prompt is flagged, the error.code value in the message is set to contentFilter. Here's an example:

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Your task failed as a result of our safety system."
    }
}

It's also possible that the generated image itself is filtered. In this case, the error message is set to Generated image was filtered as a result of our safety system.. Here's an example:

{
    "created": 1698435368,
    "error":
    {
        "code": "contentFilter",
        "message": "Generated image was filtered as a result of our safety system."
    }
}

Writing image prompts

Your image prompts should describe the content you want to see in the image, as well as the visual style of image.

Tip

For a thorough look at how you can tweak your text prompts to generate different kinds of images, see the Dallery DALL-E 2 prompt book.

When writing prompts, consider that the image generation APIs come with a content moderation filter. If the service recognizes your prompt as harmful content, it doesn't generate an image. For more information, see Content filtering.

Prompt transformation

DALL-E 3 includes built-in prompt rewriting to enhance images, reduce bias, and increase natural variation of images.

Example text prompt Example generated image without prompt transformation Example generated image with prompt transformation
"Watercolor painting of the Seattle skyline" Watercolor painting of the Seattle skyline (simple). Watercolor painting of the Seattle skyline, with more detail and structure.

The updated prompt is visible in the revised_prompt field of the data response object.

While it is not currently possible to disable this feature, you can use special prompting to get outputs closer to your original prompt by adding the following to it: I NEED to test how the tool works with extremely simple prompts. DO NOT add any detail, just use it AS-IS:.

Specify API options

The following API body parameters are available for DALL-E image generation.

Size

Specify the size of the generated images. Must be one of 1024x1024, 1792x1024, or 1024x1792 for DALL-E 3 models. Square images are faster to generate.

Style

DALL-E 3 introduces two style options: natural and vivid. The natural style is more similar to the DALL-E 2 default style, while the vivid style generates more hyper-real and cinematic images.

The natural style is useful in cases where DALL-E 3 over-exaggerates or confuses a subject that's meant to be more simple, subdued, or realistic.

The default value is vivid.

Quality

There are two options for image quality: hd and standard. hd creates images with finer details and greater consistency across the image. standard images can be generated faster.

The default value is standard.

Number

With DALL-E 3, you cannot generate more than one image in a single API call: the n parameter must be set to 1. If you need to generate multiple images at once, make parallel requests.

Response format

The format in which the generated images are returned. Must be one of url (a URL pointing to the image) or b64_json (the base 64-byte code in JSON format). The default is url.

Next steps