Completions

An array of messages comprising the conversation so far. Sansa supports text content only. Image URLs and audio inputs return a #400 error with code "unsupported_modality".

{"role": "system", "content": "..."}
{"role": "user", "content": "..."}
{"role": "assistant", "content": "..."}
{"role": "tool", "content": "..."}

// String content
{"role": "user", "content": "Hello"}

// ContentPart array (text only)
{"role": "user", "content": [{"type": "text", "text": "Hello"}]}

// null when assistant uses tools
{"role": "assistant", "content": null, "tool_calls": [...]}

{
  "role": "assistant",
  "content": null,
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\": \"Tokyo\"}"
    }
  }]
}

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"temp\": 22, \"unit\": \"celsius\"}"
}

Must be "sansa-auto" or null (omitted). Any other value returns a #400 with code invalid_model. Sansa auto-routes to the best underlying model. You do not choose the model directly.

If true, the response is delivered as Server-Sent Events (SSE). Compatible with OpenAI SDK streaming. Usage data is always included in the final streaming chunk. The stream_options parameter is accepted but ignored.

See Streaming for the full streaming reference.

Sampling temperature between 0 and 2. Higher values produce more random output; lower values produce more deterministic output. Forwarded to the underlying model. Sansa generally performs best when this is left at the default. Override only when you have a specific reason.

Maximum number of tokens to generate. Must be at least 1 if provided. Deprecated by OpenAI in favor of max_completion_tokens. Still accepted by Sansa. If both are set, max_completion_tokens takes precedence.

Upper bound on the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. Must be at least 1 if provided.

Takes precedence over max_tokens when both are set.

A list of tools the model may call. Each tool has type: "function" and a function object containing name, description, and parameters (a JSON Schema object).

See Tools for the full tool call lifecycle.

Controls which tool (if any) the model calls.

• "auto" -- model decides whether to call a tool or generate text. Default when tools is present.
• "none" -- model will not call any tool. Default when no tools are provided.
• "required" -- model must call at least one tool.
• {"type": "function", "function": {"name": "my_function"}} -- forces the model to call the named function.

Whether to allow the model to make multiple tool calls in a single response. When true, the model can return multiple entries in the tool_calls array.

Forces the model to produce output in a specific format.

• {"type": "text"} -- default. Unstructured text output.
• {"type": "json_object"} -- model output is guaranteed to be valid JSON.
• {"type": "json_schema", "json_schema": {"name": "...", "strict": true, "schema": {...}}} -- structured outputs. The response conforms to the provided JSON Schema.

json_schema is preferred over json_object when the underlying model supports it.

Reasoning (extended thinking) configuration, following the OpenRouter convention.

If both reasoning and reasoning_effort are provided, reasoning takes precedence.

The router uses this as an input to model selection. The final reasoning effort applied may differ from what you requested.

See Reasoning for full details.

Top-level OpenAI-style reasoning effort. Accepted values: "xhigh", "high", "medium", "low", "minimal", "none".

Normalized internally to a reasoning object. If both reasoning and reasoning_effort are present, reasoning takes precedence.

Nucleus sampling. Value between 0 and 1. The model considers only the tokens comprising the top top_p probability mass.

Forwarded directly to the underlying model. Not used by Sansa's routing logic. Altering both top_p and temperature simultaneously is generally not recommended.

Up to 4 sequences where the model will stop generating further tokens. The returned text will not contain the stop sequence.

Forwarded directly to the underlying model.

Number between -2.0 and 2.0. Positive values penalize tokens based on their existing frequency in the text so far, reducing repetition.

Forwarded directly to the underlying model.

Number between -2.0 and 2.0. Positive values penalize tokens based on whether they have already appeared in the text, encouraging the model to cover new topics.

Forwarded directly to the underlying model.

A set of up to 16 key-value pairs that can be attached to the request. Keys: max 64 characters. Values: max 512 characters.

The key call_name is special: its value labels the request in the Sansa dashboard. call_name must be 64 characters or less and cannot be empty or whitespace-only. There is no top-level call_name parameter -- it lives exclusively inside metadata.

Number of completions to generate. Only n=1 is accepted. Requests with n > 1 return a #400 error with code unsupported_parameter.

Audio output configuration. Sansa is text-only. Providing this parameter returns a #400 error with code unsupported_parameter.

Output modalities. Only ["text"] is accepted. Including "audio" returns a #400 error with code unsupported_parameter.

Web search configuration. Not supported. Returns a #400 error with code unsupported_parameter.

Legacy function definitions. Replaced by tools. Returns a #400 error with code unsupported_parameter.

Legacy function call control. Replaced by tool_choice. Returns a #400 error with code unsupported_parameter.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored. Sansa always includes usage data in the final streaming chunk regardless of this setting.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.

Accepted for compatibility. Silently ignored.