How to beginner · 4 min read

How to use arrays in OpenAI structured outputs

Q: How to use arrays in OpenAI structured outputs

Use the OpenAI SDK's chat.completions.create method with a prompt instructing the model to output JSON arrays. Parse the response.choices[0].message.content as JSON to handle arrays in structured outputs reliably.

Quick answer

Use the OpenAI SDK's chat.completions.create method with a prompt instructing the model to output JSON arrays. Parse the response.choices[0].message.content as JSON to handle arrays in structured outputs reliably.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official openai Python SDK version 1 or higher and set your API key as an environment variable.

Run pip install openai>=1.0
Set your API key in your shell: export OPENAI_API_KEY='your_api_key' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key" (Windows)

bash

pip install openai>=1.0

Step by step

This example shows how to prompt gpt-4o to return a JSON array in its response. The output is parsed from the string to a Python list for further use.

python

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

prompt = (
    "Return a JSON array of three fruits with their colors, e.g.,"
    " [{\"name\": \"apple\", \"color\": \"red\"}, ...]"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": prompt}]
)

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

try:
    fruits = json.loads(output_text)
    print("Parsed array:", fruits)
except json.JSONDecodeError:
    print("Failed to parse JSON. Raw output:", output_text)

output

Parsed array: [{'name': 'apple', 'color': 'red'}, {'name': 'banana', 'color': 'yellow'}, {'name': 'grape', 'color': 'purple'}]

Common variations

You can use other models like gpt-4.1 or gpt-4o-mini with the same approach. For asynchronous calls, use Python's asyncio with the OpenAI SDK's async client methods. Streaming is not supported for structured outputs parsing directly but can be combined with buffering.

python

import os
import json
import asyncio
from openai import OpenAI

async def main():
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    prompt = "Return a JSON array of three cities with their populations."
    response = await client.chat.completions.acreate(
        model="gpt-4.1",
        messages=[{"role": "user", "content": prompt}]
    )
    output_text = response.choices[0].message.content
    data = json.loads(output_text)
    print(data)

asyncio.run(main())

output

[{"city": "New York", "population": 8419000}, {"city": "Los Angeles", "population": 3980000}, {"city": "Chicago", "population": 2716000}]

Troubleshooting

If JSON parsing fails, verify the model output is valid JSON by printing response.choices[0].message.content.
Use explicit instructions in your prompt to enforce JSON formatting.
Wrap parsing in try-except to handle malformed outputs gracefully.
Consider using json.loads only after confirming output starts with [ or {.

✅

Key Takeaways

Always instruct the model clearly to output JSON arrays for structured data.
Parse the model's text output with json.loads to convert arrays into Python lists.
Use the official OpenAI SDK v1+ with environment variable API keys for secure access.
Handle JSON parsing errors gracefully with try-except blocks.
Async calls with the OpenAI SDK support the same structured output approach.

Verified 2026-04 · gpt-4o-mini, gpt-4.1, gpt-4o-mini

Verify ↗