Structured outputs

Use response_format when your code needs to parse the model’s reply. The model then responds with JSON in message.content.

`response_format.type`	Output
`text`	Plain text. This is the behavior when `response_format` is omitted.
`json_object`	A valid JSON object.
`json_schema`	JSON that matches the schema you supply.

JSON schema

Set type to json_schema and pass a json_schema object with a name (up to 64 characters) and a JSON Schema schema. You can also add a description. A json_schema request without the json_schema object returns a 400 error with code missing_required_parameter.

curl https://api.reflection.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $REFLECTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Beam-501B-A23B",
    "messages": [
      {"role": "user", "content": "Extract the event: Team offsite in Lisbon on May 4, 2027."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "event",
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "city": {"type": "string"},
            "date": {"type": "string", "description": "ISO 8601 date"}
          },
          "required": ["name", "city", "date"],
          "additionalProperties": false
        }
      }
    }
  }'

import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.reflection.ai/openai/v1",
    api_key=os.environ["REFLECTION_API_KEY"],
)

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "city": {"type": "string"},
        "date": {"type": "string", "description": "ISO 8601 date"},
    },
    "required": ["name", "city", "date"],
    "additionalProperties": False,
}

completion = client.chat.completions.create(
    model="Beam-501B-A23B",
    messages=[
        {"role": "user", "content": "Extract the event: Team offsite in Lisbon on May 4, 2027."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "event", "schema": schema},
    },
)

choice = completion.choices[0]
if choice.finish_reason != "stop" or choice.message.refusal or not choice.message.content:
    raise RuntimeError(
        f"No structured output (finish_reason={choice.finish_reason}, "
        f"refusal={choice.message.refusal})"
    )

event = json.loads(choice.message.content)
print(event["city"])

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.reflection.ai/openai/v1",
  apiKey: process.env.REFLECTION_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "Beam-501B-A23B",
  messages: [
    { role: "user", content: "Extract the event: Team offsite in Lisbon on May 4, 2027." },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "event",
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          city: { type: "string" },
          date: { type: "string", description: "ISO 8601 date" },
        },
        required: ["name", "city", "date"],
        additionalProperties: false,
      },
    },
  },
});

const choice = completion.choices[0];
if (choice.finish_reason !== "stop" || choice.message.refusal || !choice.message.content) {
  throw new Error(
    `No structured output (finish_reason=${choice.finish_reason}, refusal=${choice.message.refusal})`,
  );
}

const event = JSON.parse(choice.message.content);
console.log(event.city);

Output

{"name": "Team offsite", "city": "Lisbon", "date": "2027-05-04"}

Strict mode

Set json_schema.strict to true to enable strict schema adherence. In strict mode, schema must be an object schema in which every object sets additionalProperties: false and lists all of its properties in required, as the example above does. Strict schemas can’t use these keywords: allOf, oneOf, not, if, then, else, contains, minContains, maxContains, uniqueItems, unevaluatedItems, propertyNames, minProperties, maxProperties, unevaluatedProperties, dependentRequired, dependentSchemas, patternProperties, multipleOf, exclusiveMinimum, and exclusiveMaximum. Some keyword combinations and pattern constructs are also refused. The same rules apply to a tool’s parameters when the tool sets strict: true. See Tool calling.

JSON mode

{"type": "json_object"} asks for any valid JSON object, without a schema. Describe the shape you want in the prompt, and say that the answer should be JSON. JSON mode doesn’t apply a schema, so a request that sends json_schema with type: "json_object" or type: "text" returns a 400 error with code unsupported_parameter. To have the output match a schema, use type: "json_schema".

Handle edge cases

Before parsing content, check the response:

finish_reason: "length" means the output was cut off and is probably not valid JSON. Raise max_completion_tokens.
A non-null message.refusal means the model declined the request; content does not contain your JSON.

To have the model return arguments for your own functions rather than a final answer, use tool calling instead.

Get started

Coding agents

Mirror CLI

Guides

Resources

JSON schema

Strict mode

JSON mode

Handle edge cases

​JSON schema

​Strict mode

​JSON mode

​Handle edge cases

JSON schema

Strict mode

JSON mode

Handle edge cases