Parameters

Every option the Generate and Streaming endpoints accept.

Every parameter is optional except a prompt or messages. Leave one out and Aivana uses its default. This page is the canonical definition: the SDKs and the command line expose the same options (Python spells them in snake_case, Node.js in camelCase).

There are two kinds, and they are not the same. Prompt-defined JSON asks for JSON in your prompt and is best effort. JSON Schema (Strict) is checked against a schema you supply, and fails rather than return something that doesn't match. A worked example of each is in Structured Outputs.

Set output_shape to extract and the answer is returned as JSON. It is also returned already parsed in the structured field, so your code doesn't have to parse the text. Aivana decides the fields from your prompt, so say which ones you want.

curl https://api.aivana.ai/v1/generate \
  -H "X-API-Key: $AIVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "From this email, extract the invoice number, date and total as JSON with the keys invoice_number, date and total: ...", "output_shape": "extract"}'

{
  "answer": "{\"invoice_number\": \"INV-1042\", \"date\": \"2026-09-14\", \"total\": 1280.5}",
  "structured": { "invoice_number": "INV-1042", "date": "2026-09-14", "total": 1280.5 },
  "structured_error": null
}

If the answer isn't a JSON object (for example, it is a list, or isn't valid JSON), structured is null and structured_error says why. The answer field always carries the text, so you never get an empty response and can fall back to it. With text output, structured isn't set.

Set response_format to {"type": "json_schema", "schema": {...}} and Aivana returns a response that validates against your schema, or fails. A response that doesn't match is never returned with a 200. On success, structured holds the validated object and answer holds the same value as compact JSON.

The root of your schema must be an object, and every schema in it must say its type. Supported:

Not supported: $ref and $defs, oneOf, anyOf, allOf, not, if/then/else, pattern, format, patternProperties, uniqueItems, multipleOf, exclusiveMinimum, exclusiveMaximum, minProperties, maxProperties, and any keyword not listed above. A schema that uses one is refused with a 422 (code invalid_response_schema) before anything runs, rather than being partly honored.

• Limits: a schema can be up to 32 KiB as compact JSON, and nested up to 10 levels deep. The root is level 1; each object property and each array's items go one level deeper.
• output_shape: leave it out, or leave it auto. Any other value beside response_format is refused with a 422, because it would be a second, competing instruction about the shape.
• stop_sequences and continue are refused with a 422 beside a JSON Schema response_format: they would cut or extend the JSON.
• max_tokens still applies. If the cap is too small to hold a valid object, the request fails with structured_output_failed and isn't charged.
• It isn't streamed. Use Generate; POST /v1/generate:stream refuses it with the code structured_output_streaming_not_supported. See Streaming.
• {"type": "text"} is an ordinary answer, the same as output_shape text.

• Requests over the size limit are refused with 413. Request bodies can be up to 64 MB (files included); attachment limits are on the Files & Documents page.
• Out-of-range values are refused with a 422 that names the field.
• There is no parameter for choosing a model or provider.