Structured output

Ship features that need reliable JSON — extracted fields, labels, configs — without adding recovery logic. With Meta Model API you define the JSON Schema in response_format, and the model constrains decoding to match it exactly.

Understand how it works

Set response_format to type: "json_schema" and provide your schema in the json_schema field. The model constrains token generation to produce only valid JSON matching your schema. This is not post-processing: decoding itself is constrained, so the output is guaranteed to conform.

Recursive schemas aren't supported

Recursive schemas (schemas that reference themselves, such as tree or linked-list structures) are not supported. A request containing a recursive JSON schema returns HTTP 400. Flatten recursive structures into a fixed-depth representation instead.

text.format vs response_format

text.format is the Responses API parameter for structured output. response_format is the Chat Completions equivalent for structured output. A parameter from the other endpoint does not configure structured output, even when accepted for compatibility.

Benefits:

  • Consistent format: Output always follows your defined structure, so you can drop brittle parsing logic.
  • Reduced errors: No unexpected variations in response shape.
  • Simpler integration: Feed model output directly to APIs, databases, or downstream services that expect structured data.

Choose the right use cases

Structured output fits tasks where shape matters:

  • Extracting information: Pull names, dates, locations, or product details from unstructured text.
  • Classifying data: Categorize input into predefined labels or categories.
  • Generating function arguments: Produce structured arguments for downstream functions or APIs from natural language.
  • Generating configurations: Create JSON configuration files from user requirements.

Using a JSON schema

Define your schema directly in response_format. The schema follows standard JSON Schema syntax.

The example below extracts an address into a structured object.

python
import os
​
from openai import OpenAI
​
client = OpenAI(
    base_url="https://api.meta.ai/v1",
    api_key=os.environ["MODEL_API_KEY"],
)
​
response = client.chat.completions.create(
    model="muse-spark-1.3",
    messages=[
        {
            "role": "system",
            "content": "Extract the address from the user input into the specified JSON format.",
        },
        {
            "role": "user",
            "content": "Please format this address: 1 Hacker Wy Menlo Park CA 94025",
        },
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "Address",
            "schema": {
                "type": "object",
                "properties": {
                    "street": {
                        "type": "string",
                    },
                    "city": {
                        "type": "string",
                    },
                    "state": {
                        "type": "string",
                        "description": "2-letter state abbreviation",
                    },
                    "zip": {
                        "type": "string",
                        "description": "5-digit zip code",
                    },
                },
                "required": [
                    "street",
                    "city",
                    "state",
                    "zip",
                ],
            },
        },
    },
)
​
print(response.model_dump_json(indent=2))