Structured Output

The response_format field on POST /v1/chat/completions controls the shape of the model’s output. Use it to get back machine-readable JSON instead of free-form prose — ideal for data extraction, classification, and tool-style workflows.

POST https://api.meshapi.ai/v1/chat/completions
Authorization: Bearer rsk_<your_key>

Not every model enforces response_format. It only takes effect on models that support structured output. On many models that don’t, the request still succeeds and returns ordinary text; on others (DeepSeek, Arcee and ILMU, which implement only json_object) a json_schema request is rejected with a 4xx. So if you get prose or an error back instead of the JSON you asked for, the model most likely doesn’t support structured output: check its support on the Models page in your dashboard (app.meshapi.ai → Models, i.e. https://app.meshapi.ai/org/<your-org-id>/models) or the supports_structured_output flag returned by GET /v1/models, and switch to one with first-class support such as OpenAI models or Google Gemini (e.g. google/gemini-2.5-flash). See Not getting JSON back? and How it works across providers.

Output modes

response_format is an object whose type selects the mode:

`type`	Behavior
`"text"`	Default. Free-form text — identical to omitting `response_format`.
`"json_object"`	The model returns syntactically valid JSON. You describe the desired keys in your prompt; the structure is not otherwise enforced.
`"json_schema"`	The model returns JSON that conforms to the JSON Schema you supply. The strongest option — field names and types are constrained regardless of the prompt.

In every mode the JSON is returned as a string in choices[0].message.content, which you parse client-side.

Schema-enforced output (`json_schema`)

Supply a json_schema object containing a name (a label) and a schema (the JSON Schema to enforce):

curl
Python SDK
Node.js SDK

curl https://api.meshapi.ai/v1/chat/completions \
  -H "Authorization: Bearer rsk_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "What is the capital of France? Use the provided schema."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "country_info",
        "schema": {
          "type": "object",
          "properties": {
            "country": {"type": "string"},
            "capital": {"type": "string"}
          },
          "required": ["country", "capital"],
          "additionalProperties": false
        }
      }
    }
  }'

The Python SDK’s chat.completions.parse() takes a Pydantic model, a TypedDict/dataclass, or a raw schema dict, and returns a parsed, typed result — no manual schema dict or json.loads() needed.

from pydantic import BaseModel
from meshapi import ChatCompletionParams, ChatMessage, MeshAPI

client = MeshAPI(base_url="https://api.meshapi.ai", token="rsk_...")

class CountryInfo(BaseModel):
    country: str
    capital: str

country = client.chat.completions.parse(
    ChatCompletionParams(
        model="google/gemini-2.5-flash",
        messages=[
            ChatMessage(role="user", content="What is the capital of France?")
        ],
        temperature=0,
    ),
    response_format=CountryInfo,
)

print(country.capital)  # "Paris" — a typed CountryInfo instance

See Structured Output in the Python SDK reference for the TypedDict/raw-dict paths and the opt-in retry loop.

const schema = {
  type: "json_schema",
  json_schema: {
    name: "country_info",
    schema: {
      type: "object",
      properties: {
        country: { type: "string" },
        capital: { type: "string" },
      },
      required: ["country", "capital"],
      additionalProperties: false,
    },
  },
};

const resp = await client.chat.completions.create({
  model: "google/gemini-2.5-flash",
  messages: [
    { role: "user", content: "What is the capital of France? Use the provided schema." },
  ],
  response_format: schema,
  temperature: 0,
});

const data = JSON.parse(resp.choices[0].message?.content ?? "{}");
console.log(data.capital); // "Paris"

Valid JSON without a schema (`json_object`)

When you only need parseable JSON and don’t want to define a schema, use json_object and describe the keys you expect in the prompt:

curl https://api.meshapi.ai/v1/chat/completions \
  -H "Authorization: Bearer rsk_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {"role": "system", "content": "Respond only with JSON."},
      {"role": "user", "content": "List three fruits and their colors with keys name and color."}
    ],
    "response_format": {"type": "json_object"}
  }'

The output is guaranteed to be valid JSON, but the exact keys depend on the model following your prompt. Use json_schema when you need that guarantee.

How it works across providers

response_format follows the OpenAI convention and is forwarded to the upstream provider. For providers with a different native contract, MeshAPI translates it automatically:

Google Gemini on Vertex AI: converted to Gemini’s native structured-output config (responseMimeType for json_object, plus responseSchema for json_schema), so schema enforcement runs on the provider side.
Amazon Bedrock (including Anthropic Claude models served there): json_schema is converted to Bedrock’s native structured-output config. Bedrock can’t combine it with tool use, so on a request that also carries tools, response_format is dropped. json_object has no Bedrock equivalent, so describe the JSON in your prompt.
DeepSeek, Arcee, ILMU: json_object only; json_schema is rejected upstream with a 4xx.

Structured output works with any model that supports response_format. Elsewhere a model may return ordinary text or reject the request.

Tips

Set additionalProperties: false in your schema to forbid extra fields.
Use temperature: 0 for the most deterministic, schema-faithful output.
The content is a JSON string — parse it with json.loads() / JSON.parse().
On success finish_reason is "stop".

Not getting JSON back?

If the response comes back as ordinary prose instead of the JSON you asked for, the model you chose doesn’t support structured output, or (on Bedrock) the request also carried tools. response_format is forwarded to the provider, but a provider that ignores it returns plain text. The request still succeeds with finish_reason: "stop", so this fails silently rather than erroring.

Check that your model supports structured output. Open the Models page in your dashboard — app.meshapi.ai → Models (https://app.meshapi.ai/org/<your-org-id>/models) — and confirm the model lists Structured output support, or read the supports_structured_output flag from GET /v1/models. Models with first-class support include OpenAI models and Google Gemini (e.g. google/gemini-2.5-flash).

Common errors

HTTP	Meaning
`401`	Missing or invalid API key
`402`	Balance or spend limit issue
`400`	The provider rejected the `response_format` (for example `json_schema` on a model that only supports `json_object`, or an invalid schema)
`422`	Invalid request body, for example `response_format` is not a JSON object
`429`	Rate limit exceeded

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh Code

Mesh CLI

Platform

Reference

Structured Output

Output modes

Schema-enforced output (`json_schema`)

Valid JSON without a schema (`json_object`)

How it works across providers

Tips

Not getting JSON back?

Common errors

​Output modes

​Schema-enforced output (json_schema)

​Valid JSON without a schema (json_object)

​How it works across providers

​Tips

​Not getting JSON back?

​Common errors

Output modes

Schema-enforced output (`json_schema`)

Valid JSON without a schema (`json_object`)

How it works across providers

Tips

Not getting JSON back?

Common errors