Structured Outputs

Get responses your application can rely on: ordinary text, prompt-defined JSON, or JSON validated against your own schema.

Make AI responses predictable for your application. Aivana can return ordinary text, prompt-defined JSON, or a response validated against a JSON Schema you provide.

Describe the fields you want in your prompt and set output_shape to extract. This is useful when structured data helps but an exact guarantee isn't required. The answer is also returned parsed in structured, which is null if it couldn't be parsed. Nothing checks it against a schema. See Parameters.

You define the exact structure your application expects. Aivana validates the response against your schema before returning it. If it can't produce a response that conforms, the request fails instead of returning malformed data, and you aren't charged.

A worked example: an invoice goes in, validated fields come out.

Invoice text  →  Aivana MMI  →  vendor, invoice_number, due_date, total, past_due (validated)

curl https://api.aivana.ai/v1/generate \
  -H "X-API-Key: $AIVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract the invoice details from this text. Invoice INV-2041 from Northwind Supplies Ltd. Payment was due on 2026-09-22 and has not been received. Total due: $1,250.00. Status: overdue",
    "response_format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "vendor": { "type": "string" },
          "invoice_number": { "type": "string" },
          "due_date": { "type": ["string", "null"] },
          "total": { "type": "number" },
          "past_due": { "type": "boolean" }
        },
        "required": ["vendor", "invoice_number", "total", "past_due"],
        "additionalProperties": false
      }
    }
  }'

Your schema goes out exactly as you wrote it: the SDKs don't re-case or reorder your property names. The response:

{
  "answer": "{\"vendor\":\"Northwind Supplies Ltd\",\"invoice_number\":\"INV-2041\",\"due_date\":\"2026-09-22\",\"total\":1250,\"past_due\":true}",
  "structured": {
    "vendor": "Northwind Supplies Ltd",
    "invoice_number": "INV-2041",
    "due_date": "2026-09-22",
    "total": 1250,
    "past_due": true
  },
  "usage": { "input_tokens": 190, "output_tokens": 38, "cached_tokens": 0, "credits": 0.0003 },
  "finish_reason": "stop",
  "notices": []
}

structured is the validated object, and answer is the same value as compact JSON. They aren't two sources of truth: use whichever suits your code. Both are in Responses & Usage.

• Non-streaming. The response is checked before any of it is sent, so use Generate; the streaming endpoint refuses it. See Streaming.
• A bounded subset of JSON Schema. The root must be an object, and a keyword Aivana doesn't support is refused up front, never quietly ignored. The supported keywords, the limits (32 KiB, 10 levels deep) and what can't be combined with it are on Parameters.
• Billing. Your schema counts once toward input tokens, however Aivana produces the answer, so a response that needed more work costs the same as one that didn't. A request that fails isn't charged. See Pricing & Billing.
• Errors. A schema Aivana can't accept is a 422 with the code invalid_response_schema. A valid schema Aivana couldn't satisfy is a 502 with the code structured_output_failed. Both are listed on Errors & Retries.
• Time. A strict response is returned whole, so allow for it the way you would for any non-streaming call.

In the Playground, set Response Format to Structured, then Structured Output to JSON Schema (Strict). Edit the schema, send a request, and look for Schema validated under the answer. The Code tab gives you the same request as cURL, Python or Node.js.