Structured Outputs

OpenAI Chat Completions Structured Outputs with AI Gateway

Generate structured JSON responses that conform to a specific schema, ensuring predictable and reliable data formats for your applications.

JSON Schema format

Use the OpenAI standard json_schema response format for the most robust structured output experience. This follows the official OpenAI Structured Outputs specification.

Example request

structured-output-json-schema.ts

import OpenAI from 'openai';
 
const apiKey = process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN;
 
const openai = new OpenAI({
  apiKey,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const completion = await openai.chat.completions.create({
  model: 'openai/gpt-6-astra',
  messages: [
    {
      role: 'user',
      content: 'Create a product listing for a wireless gaming headset.',
    },
  ],
  stream: false,
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'product_listing',
      description: 'A product listing with details and pricing',
      schema: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
            description: 'Product name',
          },
          brand: {
            type: 'string',
            description: 'Brand name',
          },
          price: {
            type: 'number',
            description: 'Price in USD',
          },
          category: {
            type: 'string',
            description: 'Product category',
          },
          description: {
            type: 'string',
            description: 'Product description',
          },
          features: {
            type: 'array',
            items: { type: 'string' },
            description: 'Key product features',
          },
        },
        required: ['name', 'brand', 'price', 'category', 'description'],
        additionalProperties: false,
      },
    },
  },
});
 
console.log('Assistant:', completion.choices[0].message.content);
 
// Parse the structured response
const structuredData = JSON.parse(completion.choices[0].message.content ?? 'null');
console.log('Structured Data:', structuredData);

structured-output-json-schema.py

import os
import json
from openai import OpenAI
 
api_key = os.getenv('AI_GATEWAY_API_KEY') or os.getenv('VERCEL_OIDC_TOKEN')
 
client = OpenAI(
    api_key=api_key,
    base_url='https://ai-gateway.vercel.sh/v1'
)
 
completion = client.chat.completions.create(
    model='openai/gpt-6-astra',
    messages=[
        {
            'role': 'user',
            'content': 'Create a product listing for a wireless gaming headset.'
        }
    ],
    stream=False,
    response_format={
        'type': 'json_schema',
        'json_schema': {
            'name': 'product_listing',
            'description': 'A product listing with details and pricing',
            'schema': {
                'type': 'object',
                'properties': {
                    'name': {
                        'type': 'string',
                        'description': 'Product name'
                    },
                    'brand': {
                        'type': 'string',
                        'description': 'Brand name'
                    },
                    'price': {
                        'type': 'number',
                        'description': 'Price in USD'
                    },
                    'category': {
                        'type': 'string',
                        'description': 'Product category'
                    },
                    'description': {
                        'type': 'string',
                        'description': 'Product description'
                    },
                    'features': {
                        'type': 'array',
                        'items': {'type': 'string'},
                        'description': 'Key product features'
                    }
                },
                'required': ['name', 'brand', 'price', 'category', 'description'],
                'additionalProperties': False
            },
        }
    }
)
 
print('Assistant:', completion.choices[0].message.content)
 
# Parse the structured response
structured_data = json.loads(completion.choices[0].message.content)
print('Structured Data:', json.dumps(structured_data, indent=2))

structured-output.sh

curl -X POST "https://ai-gateway.vercel.sh/v1/chat/completions" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {
        "role": "user",
        "content": "Create a product listing for a wireless gaming headset."
      }
    ],
    "stream": false,
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "product_listing",
        "description": "A product listing with details and pricing",
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Product name"
            },
            "brand": {
              "type": "string",
              "description": "Brand name"
            },
            "price": {
              "type": "number",
              "description": "Price in USD"
            },
            "category": {
              "type": "string",
              "description": "Product category"
            },
            "description": {
              "type": "string",
              "description": "Product description"
            },
            "features": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Key product features"
            }
          },
          "required": [
            "name",
            "brand",
            "price",
            "category",
            "description"
          ],
          "additionalProperties": false
        }
      }
    }
  }'

Response format

The response contains structured JSON that conforms to your specified schema:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "openai/gpt-6-astra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"SteelSeries Arctis 7P\",\"brand\":\"SteelSeries\",\"price\":149.99,\"category\":\"Gaming Headsets\",\"description\":\"Wireless gaming headset with 7.1 surround sound\",\"features\":[\"Wireless 2.4GHz\",\"7.1 Surround Sound\",\"24-hour battery\",\"Retractable microphone\"]}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 45,
    "total_tokens": 70
  }
}

JSON Schema parameters

type: Must be "json_schema"
json_schema: Object containing schema definition
- name (required): Name of the response schema
- description (optional): Human-readable description of the expected output
- schema (required): Valid JSON Schema object defining the structure

Legacy JSON format (alternative)

Legacy format: The following format is supported for backward compatibility. For new implementations, use the json_schema format above.

structured-output-legacy.ts

import OpenAI from 'openai';
 
const apiKey = process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN;
 
const openai = new OpenAI({
  apiKey,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const completion = await openai.post<OpenAI.Chat.Completions.ChatCompletion>(
  '/chat/completions',
  {
    body: {
      model: 'openai/gpt-6-astra',
      messages: [
        {
          role: 'user',
          content: 'Create a product listing for a wireless gaming headset.',
        },
      ],
      stream: false,
 
      response_format: {
        type: 'json',
        name: 'product_listing',
        description: 'A product listing with details and pricing',
        schema: {
          type: 'object',
          properties: {
            name: {
              type: 'string',
              description: 'Product name',
            },
            brand: {
              type: 'string',
              description: 'Brand name',
            },
            price: {
              type: 'number',
              description: 'Price in USD',
            },
            category: {
              type: 'string',
              description: 'Product category',
            },
            description: {
              type: 'string',
              description: 'Product description',
            },
            features: {
              type: 'array',
              items: {
                type: 'string',
              },
              description: 'Key product features',
            },
          },
          required: ['name', 'brand', 'price', 'category', 'description'],
        },
      },
    },
  },
);
 
console.log('Assistant:', completion.choices[0].message.content);

structured-output-legacy.py

import os
import json
from openai import OpenAI
 
api_key = os.getenv('AI_GATEWAY_API_KEY') or os.getenv('VERCEL_OIDC_TOKEN')
 
client = OpenAI(
    api_key=api_key,
    base_url='https://ai-gateway.vercel.sh/v1'
)
 
completion = client.chat.completions.create(
    model='openai/gpt-6-astra',
    messages=[
        {
            'role': 'user',
            'content': 'Create a product listing for a wireless gaming headset.'
        }
    ],
    stream=False,
    response_format={
        'type': 'json',
        'name': 'product_listing',
        'description': 'A product listing with details and pricing',
        'schema': {
            'type': 'object',
            'properties': {
                'name': {'type': 'string', 'description': 'Product name'},
                'brand': {'type': 'string', 'description': 'Brand name'},
                'price': {'type': 'number', 'description': 'Price in USD'},
                'category': {'type': 'string', 'description': 'Product category'},
                'description': {'type': 'string', 'description': 'Product description'},
                'features': {
                    'type': 'array',
                    'items': {'type': 'string'},
                    'description': 'Key product features'
                }
            },
            'required': ['name', 'brand', 'price', 'category', 'description']
        }
    }
)
 
print('Assistant:', completion.choices[0].message.content)
 
# Parse the structured response
structured_data = json.loads(completion.choices[0].message.content)
print('Structured Data:', json.dumps(structured_data, indent=2))

structured-output-legacy.sh

curl -X POST "https://ai-gateway.vercel.sh/v1/chat/completions" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {
        "role": "user",
        "content": "Create a product listing for a wireless gaming headset."
      }
    ],
    "stream": false,
    "response_format": {
      "type": "json",
      "name": "product_listing",
      "description": "A product listing with details and pricing",
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Product name"
          },
          "brand": {
            "type": "string",
            "description": "Brand name"
          },
          "price": {
            "type": "number",
            "description": "Price in USD"
          },
          "category": {
            "type": "string",
            "description": "Product category"
          },
          "description": {
            "type": "string",
            "description": "Product description"
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Key product features"
          }
        },
        "required": [
          "name",
          "brand",
          "price",
          "category",
          "description"
        ]
      }
    }
  }'

Streaming with structured outputs

Both json_schema and legacy json formats work with streaming responses:

structured-streaming.ts

import OpenAI from 'openai';
 
const openai = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const stream = await openai.chat.completions.create({
  model: 'openai/gpt-6-astra',
  messages: [
    {
      role: 'user',
      content: 'Create a product listing for a wireless gaming headset.',
    },
  ],
  stream: true,
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'product_listing',
      description: 'A product listing with details and pricing',
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'Product name' },
          brand: { type: 'string', description: 'Brand name' },
          price: { type: 'number', description: 'Price in USD' },
          category: { type: 'string', description: 'Product category' },
          description: { type: 'string', description: 'Product description' },
          features: {
            type: 'array',
            items: { type: 'string' },
            description: 'Key product features',
          },
        },
        required: ['name', 'brand', 'price', 'category', 'description'],
        additionalProperties: false,
      },
    },
  },
});
 
let completeResponse = '';
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
    completeResponse += content;
  }
}
 
// Parse the complete structured response
const structuredData = JSON.parse(completeResponse);
console.log('\nParsed Product:', structuredData);

structured-streaming.py

import os
import json
from openai import OpenAI
 
client = OpenAI(
    api_key=os.getenv('AI_GATEWAY_API_KEY'),
    base_url='https://ai-gateway.vercel.sh/v1'
)
 
stream = client.chat.completions.create(
    model='openai/gpt-6-astra',
    messages=[
        {
            'role': 'user',
            'content': 'Create a product listing for a wireless gaming headset.'
        }
    ],
    stream=True,
    response_format={
        'type': 'json_schema',
        'json_schema': {
            'name': 'product_listing',
            'description': 'A product listing with details and pricing',
            'schema': {
                'type': 'object',
                'properties': {
                    'name': {'type': 'string', 'description': 'Product name'},
                    'brand': {'type': 'string', 'description': 'Brand name'},
                    'price': {'type': 'number', 'description': 'Price in USD'},
                    'category': {'type': 'string', 'description': 'Product category'},
                    'description': {'type': 'string', 'description': 'Product description'},
                    'features': {
                        'type': 'array',
                        'items': {'type': 'string'},
                        'description': 'Key product features'
                    }
                },
                'required': ['name', 'brand', 'price', 'category', 'description'],
                'additionalProperties': False
            },
        }
    }
)
 
complete_response = ''
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        content = chunk.choices[0].delta.content
        print(content, end='', flush=True)
        complete_response += content
 
# Parse the complete structured response
structured_data = json.loads(complete_response)
print('\nParsed Product:', json.dumps(structured_data, indent=2))

structured-streaming.sh

curl -X POST "https://ai-gateway.vercel.sh/v1/chat/completions" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {
        "role": "user",
        "content": "Create a product listing for a wireless gaming headset."
      }
    ],
    "stream": true,
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "product_listing",
        "description": "A product listing with details and pricing",
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Product name"
            },
            "brand": {
              "type": "string",
              "description": "Brand name"
            },
            "price": {
              "type": "number",
              "description": "Price in USD"
            },
            "category": {
              "type": "string",
              "description": "Product category"
            },
            "description": {
              "type": "string",
              "description": "Product description"
            },
            "features": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Key product features"
            }
          },
          "required": [
            "name",
            "brand",
            "price",
            "category",
            "description"
          ],
          "additionalProperties": false
        }
      }
    }
  }'

Streaming assembly: When using structured outputs with streaming, you'll need to collect all the content chunks and parse the complete JSON response once the stream is finished.

Last updated September 8, 2026

Cross-link map: OpenAI Chat Completions Structured Outputs with AI Gateway (/docs/ai-gateway/sdks-and-apis/openai-chat-completions/structured-outputs)

From the Vercel docs graph (built 2026-10-09T15:41:22.984Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

Anthropic Messages Structured Outputs with AI Gateway — Get JSON responses conforming to a JSON Schema from Anthropic models through AI Gateway.
OpenResponses Structured Outputs with AI Gateway — Request schema-constrained JSON with OpenResponses through AI Gateway, and handle provider support and response validati
AI Gateway Text Generation — Generate and stream text from hundreds of models through AI Gateway, with tool calling and structured output.
OpenAI Responses Structured Outputs with AI Gateway — Constrain a response to a JSON schema with the OpenAI Responses API through AI Gateway.
OpenAI Chat Completions Streaming with AI Gateway — Stream OpenAI Chat Completions responses token by token as they are generated through AI Gateway.

Prerequisites

AI Gateway — Vercel MCP tools for ai gateway.

Pages that link here (4)

By site: vercel-docs (4)

AI Gateway SDKs and APIs — Connect to AI Gateway with the AI SDK, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and Cohere
OpenAI Chat Completions API with AI Gateway — Use OpenAI SDKs with the AI Gateway Chat Completions API. Configure the base URL and authentication for chat, streaming,
OpenAI Chat Completions Requests with AI Gateway — Create chat completions using the Chat Completions API with support for streaming, image attachments, and PDF documents
Python with AI Gateway: OpenAI and Anthropic SDKs — Use AI Gateway with Python through OpenAI or Anthropic SDKs with full streaming, tool calling, and async support.

Tool Calling

Reasoning

Was this helpful?