|
| 1 | +--- |
| 2 | +title: 'Quickstart: Use the OpenAI Service image generation REST APIs' |
| 3 | +titleSuffix: Azure OpenAI Service |
| 4 | +description: Walkthrough on how to get started with Azure OpenAI image generation using the REST API. |
| 5 | +services: cognitive-services |
| 6 | +manager: nitinme |
| 7 | +ms.service: cognitive-services |
| 8 | +ms.subservice: openai |
| 9 | +ms.topic: include |
| 10 | +ms.date: 04/04/2023 |
| 11 | +keywords: |
| 12 | +--- |
| 13 | + |
| 14 | +Use this guide to get started calling the image generation REST APIs using Python. |
| 15 | + |
| 16 | +## Prerequisites |
| 17 | + |
| 18 | +- An Azure subscription - <a href="https://azure.microsoft.com/free/cognitive-services" target="_blank">Create one for free</a> |
| 19 | +- Access granted to DALL-E in the desired Azure subscription |
| 20 | + Currently, access to this service is granted only by application. You can apply for access to Azure OpenAI by completing the form at <a href="https://aka.ms/oai/access" target="_blank">https://aka.ms/oai/access</a>. Existing Azure OpenAI customers need to re-enter the form to get access to DALL-E. Open an issue on this repo to contact us if you have an issue. |
| 21 | +- <a href="https://www.python.org/" target="_blank">Python 3.7.1 or later version</a> |
| 22 | +- The following Python libraries: os, requests, json |
| 23 | +- An Azure OpenAI resource created in the East US region. For more information about model deployment, see the [resource deployment guide](../how-to/create-resource.md). |
| 24 | + |
| 25 | +## Retrieve key and endpoint |
| 26 | + |
| 27 | +To successfully call the Azure OpenAI APIs, you'll need the following: |
| 28 | + |
| 29 | +|Variable name | Value | |
| 30 | +|--------------------------|-------------| |
| 31 | +| `ENDPOINT` | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. Alternatively, you can find the value in **Azure OpenAI Studio** > **Playground** > **Code View**. An example endpoint is: `https://docs-test-001.openai.azure.com/`.| |
| 32 | +| `API-KEY` | This value can be found in the **Keys & Endpoint** section when examining your resource from the Azure portal. You can use either `KEY1` or `KEY2`.| |
| 33 | + |
| 34 | +Go to your resource in the Azure portal and select the **Keys and endpoint** page. Copy your endpoint and key to a temporary location. You can use either `KEY1` or `KEY2`. Always having two keys allows you to securely rotate and regenerate keys without causing a service disruption. |
| 35 | + |
| 36 | +:::image type="content" source="../media/quickstarts/endpoint.png" alt-text="Screenshot of the overview blade for an OpenAI Resource in the Azure portal with the endpoint & access keys location circled in red." lightbox="../media/quickstarts/endpoint.png"::: |
| 37 | + |
| 38 | +## Create a new Python application |
| 39 | + |
| 40 | +Create a new Python file called **quickstart.py**. Then open it up in your preferred code editor or IDE. |
| 41 | + |
| 42 | +1. Replace the contents of **quickstart.py** with the following code. Enter your endpoint URL and key in the appropriate fields. Change the value of `"prompt"` to your own custom prompt. |
| 43 | + |
| 44 | + ```python |
| 45 | + import requests |
| 46 | + import time |
| 47 | + import os |
| 48 | + api_base = 'YOUR_API_ENDPOINT_URL' |
| 49 | + api_key = 'YOUR_OPENAI_KEY' |
| 50 | + api_version = '2023-06-01-preview' |
| 51 | + url = f"{api_base}openai/images/generations:submit?api-version={api_version}" |
| 52 | + headers= { "api-key": api_key, "Content-Type": "application/json" } |
| 53 | + body = { |
| 54 | + #"prompt": "USER_PROMPT_GOES_HERE", |
| 55 | + "prompt": "A painting of a dog", |
| 56 | + "resolution": "1024x1024", |
| 57 | + "n": 1 |
| 58 | + } |
| 59 | + submission = requests.post(url, headers=headers, json=body) |
| 60 | + |
| 61 | + operation_location = submission.headers['operation-location'] |
| 62 | + status = "" |
| 63 | + while (status != "succeeded"): |
| 64 | + time.sleep(1) |
| 65 | + response = requests.get(operation_location, headers=headers) |
| 66 | + status = response.json()['status'] |
| 67 | + image_url = response.json()['result']['data'][0]['url'] |
| 68 | + ``` |
| 69 | + |
| 70 | + > [!IMPORTANT] |
| 71 | + > Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials. For example, [Azure Key Vault](../../../key-vault/general/overview.md). |
| 72 | + |
| 73 | +1. Run the application with the `python` command: |
| 74 | + |
| 75 | + ```console |
| 76 | + python quickstart.py |
| 77 | + ``` |
| 78 | + |
| 79 | + The script will make an image generation API call and then loop until the generated image is ready. |
| 80 | + |
| 81 | +## Output |
| 82 | + |
| 83 | +The output from a successful image generation API call looks like this. The `"url"` field contains a URL where you can download the generated image. The URL stays active for 24 hours. |
| 84 | + |
| 85 | +```json |
| 86 | +{ |
| 87 | + "created": 1685130482, |
| 88 | + "expires": 1685216887, |
| 89 | + "id": "088e4742-89e8-4c38-9833-c294a47059a3", |
| 90 | + "result": |
| 91 | + { |
| 92 | + "data": |
| 93 | + [ |
| 94 | + { |
| 95 | + "url": "<URL_TO_IMAGE>" |
| 96 | + } |
| 97 | + ] |
| 98 | + }, |
| 99 | + "status": "succeeded" |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +The image generation APIs come with a content moderation filter. If the service recognizes your prompt as harmful content, it won't return a generated image. For more information, see the [content filter](../concepts/content-filter.md) article. The system will return an operation status of `Failed` and the `error.code` in the message will be set to `contentFilter`. Here is an example. |
| 104 | + |
| 105 | +```json |
| 106 | +{ |
| 107 | + "created": 1589478378, |
| 108 | + "error": { |
| 109 | + "code": "contentFilter", |
| 110 | + "message": "Your task failed as a result of our safety system." |
| 111 | + }, |
| 112 | + "id": "9484f239-9a05-41ba-997b-78252fec4b34", |
| 113 | + "status": "failed" |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +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 is an example. |
| 118 | + |
| 119 | +```json |
| 120 | +{ |
| 121 | + "created": 1589478378, |
| 122 | + "expires": 1589478399, |
| 123 | + "id": "9484f239-9a05-41ba-997b-78252fec4b34", |
| 124 | + "lastActionDateTime": 1589478378, |
| 125 | + "data": [ |
| 126 | + { |
| 127 | + "url": "<URL_TO_IMAGE>" |
| 128 | + }, |
| 129 | + { |
| 130 | + "error": { |
| 131 | + "code": "contentFilter", |
| 132 | + "message": "Generated image was filtered as a result of our safety system." |
| 133 | + } |
| 134 | + } |
| 135 | + ], |
| 136 | + "status": "succeeded" |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +## Clean up resources |
| 141 | + |
| 142 | +If you want to clean up and remove an OpenAI resource, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. |
| 143 | + |
| 144 | +- [Portal](../../cognitive-services-apis-create-account.md#clean-up-resources) |
| 145 | +- [Azure CLI](../../cognitive-services-apis-create-account-cli.md#clean-up-resources) |
| 146 | + |
| 147 | +## Next steps |
| 148 | + |
| 149 | +* [Azure OpenAI Overview](../overview.md) |
| 150 | +* For more examples check out the [Azure OpenAI Samples GitHub repository](https://github.com/Azure/openai-samples). |
0 commit comments