How to beginner · 3 min read

Azure OpenAI structured outputs

Q: Azure OpenAI structured outputs

Use the AzureOpenAI client from the openai package to call chat.completions.create with your deployment name as the model. To get structured outputs, define a clear prompt requesting JSON or a schema, then parse the response.choices[0].message.content as JSON in your code.

Quick answer

Use the AzureOpenAI client from the openai package to call chat.completions.create with your deployment name as the model. To get structured outputs, define a clear prompt requesting JSON or a schema, then parse the response.choices[0].message.content as JSON in your code.

PREREQUISITES

Python 3.8+
Azure OpenAI API key
Azure OpenAI endpoint URL
pip install openai>=1.0

Setup

Install the openai Python package version 1.0 or higher. Set environment variables for your Azure OpenAI API key and endpoint URL. Use your Azure deployment name as the model parameter.

bash

pip install openai>=1.0

Step by step

This example shows how to request a structured JSON output from Azure OpenAI using the AzureOpenAI client. The prompt instructs the model to respond with a JSON object containing name and age. The response is parsed into a Python dictionary.

python

import os
import json
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01"
)

deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

prompt = (
    "Extract the user's name and age from the following text and respond with a JSON object with keys 'name' and 'age'.\n"
    "Text: 'John is 30 years old.'"
)

response = client.chat.completions.create(
    model=deployment_name,
    messages=[{"role": "user", "content": prompt}]
)

content = response.choices[0].message.content

try:
    structured_output = json.loads(content)
    print("Structured output:", structured_output)
except json.JSONDecodeError:
    print("Failed to parse JSON. Raw output:", content)

output

Structured output: {'name': 'John', 'age': 30}

Common variations

Use async calls with asyncio and await client.chat.completions.acreate(...) for asynchronous requests.
Change the prompt to request different structured formats like XML or CSV.
Use different Azure OpenAI models by changing the deployment name environment variable.

Troubleshooting

If JSON parsing fails, verify the prompt clearly instructs the model to output valid JSON.
Check that AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, and AZURE_OPENAI_DEPLOYMENT environment variables are set correctly.
Ensure you use the correct api_version parameter matching your Azure OpenAI resource.

✅

Key Takeaways

Use the AzureOpenAI client with your deployment name as the model to call Azure OpenAI chat completions.
Request structured outputs by instructing the model explicitly in the prompt to respond with JSON or a specific schema.
Parse the response.choices[0].message.content as JSON in your Python code to handle structured data.
Set environment variables for API key, endpoint, and deployment to keep credentials secure and configurable.
Troubleshoot JSON parsing errors by refining prompt instructions and verifying environment configuration.

Verified 2026-04 · gpt-4o, AzureOpenAI

Verify ↗