Merge pull request #5234 from eric-urban/eur/sora-how-to

use includes for the quickstart and other how to updates

Author: v-shils

articles/ai-services/openai/concepts/video-generation.md

@@ -6,7 +6,7 @@ ms.author: pafarley
 manager: nitinme
 ms.service: azure-ai-openai
 ms.topic: conceptual
-ms.date: 05/22/2025
+ms.date: 5/29/2025
 ---
 
 # Sora video generation (preview)
@@ -38,7 +38,7 @@ Sora has some technical limitations to be aware of:
 
 - Sora supports the following output resolution dimensions: 
 480x480, 480x854, 854x480, 720x720, 720x1280, 1280x720, 1080x1080, 1080x1920, 1920x1080.
-- Sora supports the following video durations: 5, 10, 15, and 20 seconds.
+- Sora supports video durations between 1 and 20 seconds.
 - You can request multiple video variants in a single job: for 1080p resolutions, this feature is disabled; for 720p, the maximum is two variants; for other resolutions, the maximum is four variants.
 - You can have two video creation jobs running at the same time. You must wait for one of the jobs to finish before you can create another.
 - Jobs are available for up to 24 hours after they're created. After that, you must create a new job to generate the video again.
@@ -49,3 +49,6 @@ Sora has a robust safety stack including content filtering, abuse monitoring, se
 
 Sora doesn't generate scenes with acts of violence but can generate adjacent content, such as realistic war-like footage.
 
+## Related content
+- [Video generation quickstart](../video-generation-quickstart.md)
+- [Image generation quickstart](../dall-e-quickstart.md)

articles/ai-services/openai/includes/api-versions/new-inference-preview.md

@@ -1078,12 +1078,12 @@ POST {endpoint}/openai/v1/video/generations/jobs?api-version=preview
 
 | Name | Type | Description | Required | Default |
 |------|------|-------------|----------|---------|
-| height | integer | The height of the video. The following dimensions are supported: 480x480, 854x480, 720x720, 1280x720, 1080x1080 and 1920x1080. | Yes |  |
+| height | integer | The height of the video. The following dimensions are supported: 480x480, 480x854, 854x480, 720x720, 720x1280, 1280x720, 1080x1080, 1080x1920, 1920x1080. | Yes |  |
 | model | string | The name of the deployment to use for this request. | Yes |  |
 | n_seconds | integer | The duration of the video generation job. Must be between 1 and 20 seconds. | No | 5 |
 | n_variants | integer | The number of videos to create as variants for this job. Must be between 1 and 5. Smaller dimensions allow more variants. | No | 1 |
 | prompt | string | The prompt for this video generation job. | Yes |  |
-| width | integer | The width of the video. The following dimensions are supported: 480x480, 854x480, 720x720, 1280x720, 1080x1080 and 1920x1080. | Yes |  |
+| width | integer | The width of the video. The following dimensions are supported: 480x480, 480x854, 854x480, 720x720, 720x1280, 1280x720, 1080x1080, 1080x1920, 1920x1080. | Yes |  |
 
 ### Responses
 
@@ -2276,12 +2276,12 @@ The tool calls generated by the model, such as function calls.
 
 | Name | Type | Description | Required | Default |
 |------|------|-------------|----------|---------|
-| height | integer | The height of the video. The following dimensions are supported: 480x480, 854x480, 720x720, 1280x720, 1080x1080 and 1920x1080. | Yes |  |
+| height | integer | The height of the video. The following dimensions are supported: 480x480, 480x854, 854x480, 720x720, 720x1280, 1280x720, 1080x1080, 1080x1920, 1920x1080. | Yes |  |
 | model | string | The name of the deployment to use for this request. | Yes |  |
 | n_seconds | integer | The duration of the video generation job. Must be between 1 and 20 seconds. | No | 5 |
 | n_variants | integer | The number of videos to create as variants for this job. Must be between 1 and 5. Smaller dimensions allow more variants. | No | 1 |
 | prompt | string | The prompt for this video generation job. | Yes |  |
-| width | integer | The width of the video. The following dimensions are supported: 480x480, 854x480, 720x720, 1280x720, 1080x1080 and 1920x1080. | Yes |  |
+| width | integer | The width of the video. The following dimensions are supported: 480x480, 480x854, 854x480, 720x720, 720x1280, 1280x720, 1080x1080, 1080x1920, 1920x1080. | Yes |  |
 
 ### ElasticsearchChatDataSource
 

articles/ai-services/openai/includes/video-generation-intro.md

@@ -0,0 +1,12 @@
+---
+manager: nitinme
+author: eric-urban
+ms.author: eur
+ms.service: azure-ai-openai
+ms.topic: include
+ms.date: 5/29/2025
+---
+
+In this quickstart, you generate video clips using the Azure OpenAI service. The example uses the Sora model, which is a video generation model that creates realistic and imaginative video scenes from text instructions. This guide shows you how to create a video generation job, poll for its status, and retrieve the generated video.
+
+For more information on video generation, see [Video generation concepts](../concepts/video-generation.md).

articles/ai-services/openai/includes/video-generation-rest.md

@@ -0,0 +1,136 @@
+---
+manager: nitinme
+author: eric-urban
+ms.author: eur
+ms.service: azure-ai-openai
+ms.topic: include
+ms.date: 5/29/2025
+---
+
+[!INCLUDE [Video generation introduction](video-generation-intro.md)]
+
+## Prerequisites
+
+- An Azure subscription. <a href="https://azure.microsoft.com/free/ai-services" target="_blank">Create one for free</a>.
+- <a href="https://www.python.org/" target="_blank">Python 3.8 or later version</a>. We recommend using Python 3.10 or later, but having at least Python 3.8 is required. If you don't have a suitable version of Python installed, you can follow the instructions in the [VS Code Python Tutorial](https://code.visualstudio.com/docs/python/python-tutorial#_install-a-python-interpreter) for the easiest way of installing Python on your operating system.
+- An Azure OpenAI resource created in one of the supported regions. For more information about region availability, see the [models and versions documentation](/azure/ai-services/openai/concepts/models#video-generation-models).
+- Then, you need to deploy a `sora` model with your Azure OpenAI resource. For more information, see [Create a resource and deploy a model with Azure OpenAI](../how-to/create-resource.md).
+
+## Microsoft Entra ID prerequisites
+
+For the recommended keyless authentication with Microsoft Entra ID, you need to:
+- Install the [Azure CLI](/cli/azure/install-azure-cli) used for keyless authentication with Microsoft Entra ID.
+- Assign the `Cognitive Services User` role to your user account. You can assign roles in the Azure portal under **Access control (IAM)** > **Add role assignment**.
+
+## Set up
+
+1. Create a new folder `video-generation-quickstart` and go to the quickstart folder with the following command:
+
+    ```shell
+    mkdir video-generation-quickstart && cd video-generation-quickstart
+    ```
+    
+1. Create a virtual environment. If you already have Python 3.10 or higher installed, you can create a virtual environment using the following commands:
+    
+    # [Windows](#tab/windows)
+    
+    ```bash
+    py -3 -m venv .venv
+    .venv\scripts\activate
+    ```
+    
+    # [Linux](#tab/linux)
+    
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate
+    ```
+    
+    # [macOS](#tab/macos)
+    
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate
+    ```
+    
+    ---
+    
+    Activating the Python environment means that when you run ```python``` or ```pip``` from the command line, you then use the Python interpreter contained in the ```.venv``` folder of your application. You can use the ```deactivate``` command to exit the python virtual environment, and can later reactivate it when needed.
+
+    > [!TIP]
+    > We recommend that you create and activate a new Python environment to use to install the packages you need for this tutorial. Don't install packages into your global python installation. You should always use a virtual or conda environment when installing python packages, otherwise you can break your global installation of Python.
+
+1. For the **recommended** keyless authentication with Microsoft Entra ID, install the `azure-identity` package with:
+
+    ```console
+    pip install azure-identity
+    ```
+
+
+## Retrieve resource information
+
+[!INCLUDE [resource authentication](resource-authentication.md)]
+
+
+## Generate video with Sora
+You can generate a video with the Sora model by creating a video generation job, polling for its status, and retrieving the generated video. The following code shows how to do this via the REST API using Python.
+
+## [Microsoft Entra ID](#tab/keyless)
+
+1. Create the `sora-quickstart.py` file with the following code:
+
+    ```python
+    import requests
+    import base64 
+    import os
+    from azure.identity import DefaultAzureCredential
+    
+    # Set environment variables or edit the corresponding values here.
+    endpoint = os.environ['AZURE_OPENAI_ENDPOINT']
+    
+    # Keyless authentication
+    credential = DefaultAzureCredential()
+    token = credential.get_token("https://cognitiveservices.azure.com/.default")
+    
+    api_version = '2025-01-01-preview'
+    url = f"{endpoint}/openai/deployments/gpt-4o-mini-audio-preview/chat/completions?api-version={api_version}"
+    headers= { "Authorization": f"Bearer {token.token}", "Content-Type": "application/json" }
+    ```
+
+1. Run the Python file.
+
+    ```shell
+    python sora-quickstart.py
+    ```
+
+## [API key](#tab/api-key)
+
+1. Create the `sora-quickstart.py` file with the following code:
+
+    ```python
+    import requests
+    import base64 
+    import os
+    
+    # Set environment variables or edit the corresponding values here.
+    endpoint = os.environ['AZURE_OPENAI_ENDPOINT']
+    api_key = os.environ['AZURE_OPENAI_API_KEY']
+    
+    api_version = '2025-01-01-preview'
+    url = f"{endpoint}/openai/deployments/gpt-4o-mini-audio-preview/chat/completions?api-version={api_version}"
+    headers= { "api-key": api_key, "Content-Type": "application/json" }
+    ```
+
+1. Run the Python file.
+
+    ```shell
+    python sora-quickstart.py
+    ```
+
+---
+
+Wait a few moments to get the response.
+
+### Output
+
+

articles/ai-services/openai/video-generation-quickstart.md

@@ -7,112 +7,21 @@ ms.service: azure-ai-openai
 ms.topic: quickstart
 author: PatrickFarley
 ms.author: pafarley
-ms.date: 05/22/2025
+ms.date: 5/29/2025
 ---
 
 # Quickstart: Generate a video with Sora (preview)
 
-In this quickstart, you generate video clips using the Azure OpenAI service. The example uses the Sora model, which is a video generation model that creates realistic and imaginative video scenes from text instructions. This guide shows you how to create a video generation job, poll for its status, and retrieve the generated video.
+[!INCLUDE [REST API quickstart](includes/video-generation-rest.md)]
 
-For more information on video generation, see [Video generation concepts](./concepts/video-generation.md).
+## Clean-up resources
 
+If you want to clean up and remove an Azure OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.
 
-## Prerequisites
+- [Azure portal](../multi-service-resource.md?pivots=azportal#clean-up-resources)
+- [Azure CLI](../multi-service-resource.md?pivots=azcli#clean-up-resources)
 
-- An Azure subscription. <a href="https://azure.microsoft.com/free/ai-services" target="_blank">Create one for free</a>.
-- <a href="https://www.python.org/" target="_blank">Python 3.8 or later version</a>.
-- An Azure OpenAI resource created in a supported region. See [Region availability](/azure/ai-services/openai/concepts/models#model-summary-table-and-region-availability).
-- Then, you need to deploy a `sora` model with your Azure resource. For more information, see [Create a resource and deploy a model with Azure OpenAI](./how-to/create-resource.md).
-- [Python 3.8 or later version](https://www.python.org/).
+## Related content
 
-
-## Setup
-
-### Retrieve key and endpoint
-
-To successfully call the Azure OpenAI APIs, you need the following information about your Azure OpenAI resource:
-
-| Variable | Name | Value |
-|---|---|---|
-| **Endpoint** | `api_base` | The endpoint value is located under **Keys and Endpoint** for your resource in the Azure portal. You can also find the endpoint via the **Deployments** page in Azure AI Foundry portal. An example endpoint is: `https://docs-test-001.openai.azure.com/`. |
-| **Key** | `api_key` | The key value is also located under **Keys and Endpoint** for your resource in the Azure portal. Azure generates two keys for your resource. You can use either value. |
-
-Go to your resource in the Azure portal. On the navigation pane, select **Keys and Endpoint** under **Resource Management**. Copy the **Endpoint** value and an access key value. You can use either the **KEY 1** or **KEY 2** value. Always having two keys allows you to securely rotate and regenerate keys without causing a service disruption.
-
-:::image type="content" source="./media/quickstarts/endpoint.png" alt-text="Screenshot that shows the Keys and Endpoint page for an Azure OpenAI resource in the Azure portal." lightbox="./media/quickstarts/endpoint.png":::
-
-
-
-[!INCLUDE [environment-variables](./includes/environment-variables.md)]
-
-
-
-## Create a new Python application
-
-Create a new Python file named `quickstart.py`. Open the new file in your preferred editor or IDE.
-1. Replace the contents of `quickstart.py` with the following code. Change the value of `prompt` to your preferred text.
-    
-    ```python
-    import os
-    import time
-    import requests
-    
-    # Set these variables with your values
-    endpoint = os.environ["AZURE_OPENAI_ENDPOINT"]  # e.g., "https://docs-test-001.openai.azure.com"
-    api_key = os.environ["AZURE_OPENAI_KEY"]
-    access_token = os.environ.get("AZURE_OPENAI_TOKEN")  # Optional: if using Azure AD auth
-    
-    headers = {
-        "Content-Type": "application/json",
-        "api-key": api_key,
-    }
-    if access_token:
-        headers["Authorization"] = f"Bearer {access_token}"
-    
-    # 1. Create a video generation job
-    create_url = f"{endpoint}/openai/v1/video/generations/jobs?api-version=preview"
-    payload = {
-        "prompt": "A cat playing piano in a jazz bar.",
-        "model": "sora",
-        "width": 1080,
-        "height": 1080,
-        "n_seconds": 10
-    }
-    response = requests.post(create_url, headers=headers, json=payload)
-    response.raise_for_status()
-    job_id = response.json()["body"]["id"]
-    print(f"Job created: {job_id}")
-    
-    # 2. Poll for job status
-    status_url = f"{endpoint}/openai/v1/video/generations/jobs/{job_id}?api-version=preview"
-    while True:
-        status_response = requests.get(status_url, headers=headers)
-        status_response.raise_for_status()
-        status = status_response.json()["body"]["status"]
-        print(f"Job status: {status}")
-        if status == "succeeded":
-            generations = status_response.json()["body"].get("generations", [])
-            if not generations:
-                raise Exception("No generations found in job result.")
-            generation_id = generations[0]["id"]
-            break
-        elif status in ("failed", "cancelled"):
-            raise Exception(f"Job did not succeed. Status: {status}")
-        time.sleep(5)  # Wait before polling again
-    
-    # 3. Retrieve the generated video
-    get_video_url = f"{endpoint}/openai/v1/video/generations/{generation_id}?api-version=preview"
-    video_response = requests.get(get_video_url, headers=headers)
-    video_response.raise_for_status()
-    download_url = video_response.json()["body"]["generations"]
-    print(f"Download your video at: {download_url}")
-    ```
-1. Run the application with the `python` command:
-
-    ```console
-    python quickstart.py
-    ```
-
-    Wait a few moments to get the response.
-
----
+* Learn more about Azure OpenAI [deployment types](./how-to/deployment-types.md).
+* Learn more about Azure OpenAI [quotas and limits](quotas-limits.md).