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.

Typed parsing with `parse()` (Node.js)

The Node.js SDK (2.0.0) has client.chat.completions.parse(): it builds response_format from a schema, sends a non-streaming request, and returns the parsed object. Pass a Standard Schema validator (Zod v4, Valibot with @valibot/to-json-schema, ArkType) to get a validated, typed result, or a raw JSON schema to get JSON.parse output without validation.

import { z } from "zod";
import { StructuredOutputError } from "meshapi-node-sdk";

const Country = z.object({ capital: z.string(), country: z.string() });

try {
  const result = await client.chat.completions.parse(
    {
      model: "google/gemini-2.5-flash",
      messages: [{ role: "user", content: "What is the capital of France?" }],
    },
    Country,
    { maxRetries: 2 },
  );
  console.log(result.capital); // "Paris"
} catch (err) {
  if (err instanceof StructuredOutputError) console.error("Still invalid after retries:", err.message);
  else throw err;
}

maxRetries feeds a response that fails validation back to the model with the error appended. Each retry is a billed call; the default is 0. An empty response (a refusal or a tool call) is never retried. If the response still can’t be parsed, parse() throws StructuredOutputError. The usual cause is a model that doesn’t support structured output.

parse() is not in the current Python (0.1.11) or Go (v0.1.12) releases. In those SDKs, call create() with response_format and parse choices[0].message.content yourself, as in the examples above.

​Output modes

​Basic example

​Valid JSON without a schema

​How it works across providers

​Supported models

​Notes

​Typed parsing with parse() (Node.js)

Output modes

Basic example

Valid JSON without a schema

How it works across providers

Supported models

Notes

Typed parsing with `parse()` (Node.js)