Structured output

Pass a response_format and the model is constrained toward your JSON Schema during generation. Use it for anything downstream that needs a known shape: database inserts, form filling, data extraction, classification with fixed enums.

Minimal code

The one thing to know before you run it: deepseek-v4-flash cannot hold a format while it is reasoning, so a schema on that model travels with reasoning_effort: "none" in the same request. That is why every snippet below carries the field.

import os
from openai import OpenAI
from pydantic import BaseModel

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

class Receipt(BaseModel):
    merchant: str
    total_usd: float
    date: str
    items: list[str]

response = client.beta.chat.completions.parse(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Extract the receipt fields."},
        {"role": "user", "content": "I bought coffee and a muffin at Blue Bottle on 2026-04-20 for $12.50"},
    ],
    reasoning_effort="none",
    response_format=Receipt,
)

receipt: Receipt = response.choices[0].message.parsed
print(receipt.merchant, receipt.total_usd)

import OpenAI from "openai";
import { z } from "zod";
import { zodResponseFormat } from "openai/helpers/zod";

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

const Receipt = z.object({
  merchant: z.string(),
  total_usd: z.number(),
  date: z.string(),
  items: z.array(z.string()),
});

const response = await client.chat.completions.parse({
  model: "deepseek-v4-flash",
  messages: [
    { role: "system", content: "Extract the receipt fields." },
    { role: "user", content: "I bought coffee and a muffin at Blue Bottle on 2026-04-20 for $12.50" },
  ],
  reasoning_effort: "none",
  response_format: zodResponseFormat(Receipt, "receipt"),
});

const receipt = response.choices[0].message.parsed;
console.log(receipt.merchant, receipt.total_usd);

curl https://api.runinfra.ai/v1/chat/completions \
  -H "Authorization: Bearer $RUNINFRA_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role":"system","content":"Extract the receipt fields."},
      {"role":"user","content":"I bought coffee at Blue Bottle on 2026-04-20 for $12.50"}
    ],
    "reasoning_effort": "none",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "receipt",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "merchant":  {"type":"string"},
            "total_usd": {"type":"number"},
            "date":      {"type":"string"},
            "items":     {"type":"array","items":{"type":"string"}}
          },
          "required": ["merchant","total_usd","date","items"],
          "additionalProperties": false
        }
      }
    }
  }'

The SDK parse() helpers validate the reply against your Pydantic or Zod model. The curl tab shows the raw response_format request underneath them, which is the portable form for any client.

Which model, and what it needs

Send a schema without reasoning_effort: "none" on one of the two conditional models and the request is refused with 400, param: "response_format". The refusal is deliberate: the alternative is a 200 carrying a reply your parser rejects, billed in full.

"none" is a wire value. If your installed SDK’s type definitions predate it, widen the literal at the call site. The request that goes out is unchanged.

What to tune

Parameter	Effect
`response_format: { type: "json_object" }`	Looser. Any valid JSON, no schema enforcement.
`response_format.json_schema.strict: true`	Rejects a reply that does not fit the schema. The Pydantic and Zod helpers set it for you.
`temperature: 0`	Best for deterministic extraction. Non-zero works too.
`reasoning_effort: "none"`	Required alongside a schema on the conditional models, and it also removes the reasoning tokens you would otherwise be billed for.

Common mistakes

Asking for JSON in the prompt instead of in response_format. The model can still add commentary or markdown fences. Pass the field.
Leaving additionalProperties open. Strict mode requires additionalProperties: false. The helpers set it, raw JSON Schema users must add it.
Nested anyOf without discriminators. Use enums or discriminated unions. An unbounded anyOf confuses a constrained decoder.
Expecting enums to be case-insensitive. Schema enums are exact match. "Paris" does not satisfy enum: ["paris", "berlin"].

Next steps

Tool calling

Structured arguments, then an action.

Streaming

Stream JSON that parses as it arrives.

Chat completions

The full response_format contract.

Start here

Guides

API reference

Structured output

Minimal code

Which model, and what it needs

What to tune

Common mistakes

Next steps

Tool calling

Streaming

Chat completions

​Minimal code

​Which model, and what it needs

​What to tune

​Common mistakes

​Next steps

Tool calling

Streaming

Chat completions

Minimal code

Which model, and what it needs

What to tune

Common mistakes

Next steps