> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trymaitai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Model Request
> Create chat completions with Maitai metadata (Application, Intent, Session).
export const CompletionUsageHeadline = 'Usage statistics for the completion request.';
export const StreamUsageHeadline =
An optional field that will only be present when you set stream_options with include_usage: true in your
request. When present, it contains a null value except for the last chunk which contains the token usage
statistics for the entire request.
;
export const UsageSnippet = ({headline}) =>
{headline}
Number of tokens in the generated completion.
Number of tokens in the prompt.
Total number of tokens used in the request (prompt + completion).
;
## Create chat completion
```python Python (async) theme={null}
import maitai
client = maitai.MaitaiAsync()
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Say hello in one sentence."},
]
response = await client.chat.completions.create(
messages=messages,
application="demo_app",
intent="GREETING",
session_id="YOUR_SESSION_ID",
# model="llama3-70b-8192", # Optional: omit to use Portal config
)
```
```python Python (sync) theme={null}
import maitai
client = maitai.Maitai()
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Say hello in one sentence."},
]
response = client.chat.completions.create(
messages=messages,
application="demo_app",
intent="GREETING",
session_id="YOUR_SESSION_ID",
# model="llama3-70b-8192", # Optional: omit to use Portal config
)
```
```javascript Node theme={null}
import Maitai from "maitai";
const maitai = new Maitai();
const messages = [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Say hello in one sentence." },
];
const response = await maitai.chat.completions.create({
messages: messages,
application: "demo_app",
intent: "GREETING",
session_id: "YOUR_SESSION_ID",
// model: "llama3-70b-8192", // Optional: omit to use Portal config
});
```
## Image input
```python Python (sync) theme={null}
import maitai
client = maitai.Maitai()
messages = [
{
"role": "user",
"content": [
{"type": "input_text", "text": "what's in this image?"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/0/05/Mt_Rainier_NOAA_2000.jpg",
},
],
}
]
response = client.chat.completions.create(
messages=messages,
application="demo_app",
intent="VISION",
session_id="YOUR_SESSION_ID",
model="gpt-4o-mini",
evaluation_enabled=False,
apply_corrections=False,
)
print(response.choices[0].message.content)
```
```javascript Node theme={null}
import Maitai from "maitai";
const maitai = new Maitai();
const messages = [
{
role: "user",
content: [
{ type: "input_text", text: "what's in this image?" },
{
type: "input_image",
image_url:
"https://upload.wikimedia.org/wikipedia/commons/0/05/Mt_Rainier_NOAA_2000.jpg",
},
],
},
];
const response = await maitai.chat.completions.create({
messages,
application: "demo_app",
intent: "VISION",
session_id: "YOUR_SESSION_ID",
model: "gpt-4o-mini",
evaluation_enabled: false,
apply_corrections: false,
});
console.log(response.choices[0].message.content);
```
## Maitai parameters
The Application reference name (shown in the Portal). Maitai uses this to group your traffic.
The Intent / action type for this request (also called `action_type`). This is used for organization, configuration, and quality tooling.
Optional but recommended. Groups related requests into a session in the Portal. If omitted, the SDK will generate one.
Optional metadata tags stored with the request for filtering/debugging.
Provider-agnostic reasoning controls: `effort` (`"low"` | `"medium"` | `"high"`, optional) and `summary` (boolean, default `false`) to include thinking text on the response. See [Reasoning](/sdk/reasoning).
**Deprecated.** Use the `reasoning` object with an `effort` field (for example `reasoning={"effort": "high"}` in Python or `reasoning: { effort: "high" }` in Node) instead. See [Reasoning](/sdk/reasoning). This field still works for backward compatibility.
## Evaluations and corrections (optional)
Enable/disable Sentinel evaluations for this request (Portal config also controls this).
When enabled, Maitai may apply an automatic correction if evaluations find a fault.
Corrections require server-side inference.
Prioritize accuracy over latency when applying corrections.
Optional callback invoked with the evaluation results. See [Evaluate](/sdk/evaluate).
## Inference routing
Controls where inference runs.
* true: inference is routed through Maitai (recommended). This enables server-side features like corrections and `input_safety_score`.
* false: run inference with your own client. To send those request/response pairs to Maitai for monitoring and indexing, use maitai.log() (bring your own inference).
## Fallbacks (optional)
Optional fallback configuration used when the primary model fails or times out.
Must be one of `reactive`, `first_response`, or `timeout`.
The fallback model name.
Timeout (seconds) for strategies that use a timeout.
## OpenAI parameters
Maitai accepts the standard OpenAI `chat.completions.create` parameters (for example: `model`, `temperature`, `tools`, `tool_choice`, `response_format`, `stream`, etc.). If you set them in the request, they override Portal defaults.
Related guides:
* [Structured Output](/sdk/structured_output)
* [Tool Calling](/sdk/tool_calling)
## Response fields
Maitai returns an OpenAI-compatible `chat.completion` response, plus a few extra fields:
The Maitai request identifier.
Evaluation results (when evaluations are enabled).
Whether a correction was applied.
Optional input safety score (when enabled). A number between 0 and 1 where lower values indicate a potential jailbreak attempt.
Time to first token (milliseconds), when available.
Total response time (milliseconds), when available.
Present when a fallback model was used (explains why).
## Streaming usage