Structured Output

Pass a response_format with type: "json_schema" to get a response that always matches your schema. Works with any model that supports response_format, including OpenAI and Google Gemini models (e.g. google/gemini-2.5-flash).

Not every model enforces response_format. It only takes effect on models that support structured output. If a model doesn’t, the request still succeeds and returns ordinary text — it does not error. Always parse/validate the response, and prefer a model with first-class support such as OpenAI models or Google Gemini (e.g. google/gemini-2.5-flash).

Output modes

response_format is an object whose type selects how the output is shaped:

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

In the JSON modes the content comes back as a string in choices[0].message.content — parse it client-side.

Basic example

Python
Node.js
Go

import json
from meshapi import MeshAPI, ChatCompletionParams, ChatMessage

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

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

resp = client.chat.completions.create(
    ChatCompletionParams(
        model="google/gemini-2.5-flash",
        messages=[ChatMessage(role="user", content="What is the capital of France? Use the provided schema.")],
        response_format=schema,
        max_tokens=1000,
        temperature=0,
    )
)

data = json.loads(resp.choices[0].message.content)
print(data["capital"])  # "Paris"
print(data["country"])  # "France"

const schema = {
  type: "json_schema",
  json_schema: {
    name: "country_info",
    schema: {
      type: "object",
      properties: {
        capital: { type: "string" },
        country: { type: "string" },
      },
      required: ["capital", "country"],
      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,
  max_tokens: 1000,
  temperature: 0,
});

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

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

model := "google/gemini-2.5-flash"
maxTokens := 1000
resp, err := client.Chat.Completions.Create(ctx, meshapi.ChatCompletionParams{
    Model: &model,
    Messages: []meshapi.ChatMessage{
        {Role: "user", Content: "What is the capital of France? Use the provided schema."},
    },
    ResponseFormat: schema,
    MaxTokens:      &maxTokens,
})
if err != nil {
    log.Fatal(err)
}

var data map[string]interface{}
json.Unmarshal([]byte(*resp.Choices[0].Message.Content), &data)
fmt.Println(data["capital"]) // "Paris"

Valid JSON without a schema

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

resp = client.chat.completions.create(
    ChatCompletionParams(
        model="google/gemini-2.5-flash",
        messages=[
            ChatMessage(role="system", content="Respond only with JSON."),
            ChatMessage(role="user", content="List three fruits and their colors with keys name and color."),
        ],
        response_format={"type": "json_object"},
    )
)

data = json.loads(resp.choices[0].message.content)

The output is always 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, Mesh API translates it automatically — for example, Google Gemini models on Vertex AI are converted to Gemini’s native structured-output config (responseMimeType for json_object, plus responseSchema for json_schema), so enforcement runs on the provider side.

Supported models

Structured output works with any model that supports response_format — this includes OpenAI and Google Gemini models (e.g. google/gemini-2.5-flash). Models that don’t support it simply return ordinary text. Use GET /v1/models to see the models enabled on your account.

Notes

Set additionalProperties: false to prevent extra fields in the response.
finish_reason will be "stop" on success.
The response content is a JSON string — parse it with json.loads() / JSON.parse() / json.Unmarshal.

Auto-retry on validation failure (Python)

Some models only best-effort the schema. Set max_retries on parse() to feed a failed response back to the model with the validation error appended. Each retry is a billed call; the default is 0 (no retry).

country = client.chat.completions.parse(params, Country, max_retries=3)

parse() returns the parsed object directly:

`response_format`	Returns
Pydantic `BaseModel` subclass	An instance of that model
`TypedDict` / dataclass	The validated object
Raw JSON-schema `dict`	A `dict` (`json.loads`, unvalidated)

parse() is non-streaming — use create() when you need the raw string content plus usage and cost metadata. The async client exposes the same await client.chat.completions.parse(...).

​Output modes

​Basic example

​Valid JSON without a schema

​How it works across providers

​Supported models

​Notes

​Auto-retry on validation failure (Python)

Output modes

Basic example

Valid JSON without a schema

How it works across providers

Supported models

Notes

Auto-retry on validation failure (Python)