Chat Completions API
Early accessUse the Chat Completions API to generate a response from SubQ Savant (subq-savant-1.4) for a list of conversation messages. Savant is early access, enabled per organization. Request access. For server-managed multi-turn conversations with system instructions and built-in web search, see Responses API.
POST /v1/chat/completionsRequest body
Send a JSON object with the required model and messages fields. Omit optional fields unless you need to change generation behavior.
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID to use, such as subq-savant-1.4. See Models. |
messages | array | Yes | Conversation messages in order. Must contain at least one message. |
stream | boolean | No | When false or omitted, returns one JSON response. When true, returns server-sent events. |
temperature | number | No | Fixed at 1. Omit it or send 1. Any other value returns 400 unsupported_value. See Restricted parameters. |
max_tokens | integer | No | Caps generated tokens. Must be at least 1. See Token limits. |
top_p | number | No | Nucleus sampling value from 0 to 1. |
stop | string or string[] | No | Up to 4 sequences where generation stops. |
reasoning_effort | string | No | How much the model reasons before answering: low, high (the default), or max. Reasoning cannot be turned off. See Reasoning effort. |
response_format | object | No | Constrain the assistant reply to a JSON Schema. See Structured outputs. |
tools | array | No | Function tools the model may call. See Function calling. |
tool_choice | string | No | Whether the model may call tools: "auto" (the default) or "none". See Tool choice. |
store | boolean or null | No | Set false to keep this request and response out of storage. Defaults to true. See Storage. |
metadata | object or null | No | Up to 16 key-value string pairs attached to the request, for your own tracking. Echoed back on the response. See Metadata. |
This page documents the non-streaming response. For a non-streaming request, omit stream or set it to false.
Restricted parameters
A request that breaks one of these rules returns 400, and nothing is generated.
| Parameter | Rule | code |
|---|---|---|
temperature | Fixed at 1. Omit it or send 1. | unsupported_value |
reasoning_effort | none is rejected. Reasoning cannot be turned off, including through a reasoning object with effort: "none" or enabled: false. Use low for the least reasoning. | unsupported_value |
Token limits
max_tokens caps the tokens generated in the completion, reasoning included. It does not count the prompt.
- Budget for the reasoning and the answer together. The model reasons before answering from the same allowance, so a request can return
200withcontentset tonullandfinish_reasonof"length": billed, with nothing visible. - Input and output share the 4M-token context window. If the input plus
max_tokenscannot fit, the API returns400context_length_exceeded. - Send
max_tokens, notmax_completion_tokens. - The minimum is
1. If omitted, the response can use all remaining context. - If generation hits the cap,
choices[0].finish_reasonis"length".
{
"model": "subq-savant-1.4",
"messages": [
{
"role": "user",
"content": "In three bullets, explain the difference between indemnification, limitation of liability, and insurance requirements in a software contract."
}
],
"max_tokens": 500
}Reasoning effort
SubQ Savant reasons before it answers. Set top-level reasoning_effort to control how much. Reasoning cannot be turned off: none returns 400 unsupported_value. For the least reasoning, use low.
| Value | Use it for |
|---|---|
low | Short answers, extraction, and latency-sensitive requests. |
high | The default. Most analysis, drafting, and agent loops. |
max | Hard questions over long inputs, where accuracy matters more than latency and cost. |
minimal, medium, and xhigh are accepted for OpenAI compatibility and run as low, high, and max.
- Reasoning tokens are billed as output tokens. They are included in
usage.completion_tokensand counted inmax_tokens. A one-line answer can bill many times more output tokens than its visible text. - Higher effort doesn't always use more tokens. Token use varies by prompt, so compare efforts on your own prompts.
{
"model": "subq-savant-1.4",
"messages": [
{
"role": "system",
"content": "You are a legal research assistant. Use plain language. Cite only facts in the conversation."
},
{
"role": "user",
"content": "Summarize the major self-preferencing antitrust cases since 2010 and list open questions for counsel."
}
],
"reasoning_effort": "max"
}For classification and routing with probabilities, use the Decisions API.
Reasoning output
The model's reasoning comes back separately from its answer, so content holds only the answer.
| Field | Contains |
|---|---|
choices[0].message.reasoning | The reasoning text. null if the response has no reasoning text. |
choices[0].delta.reasoning | When streaming, reasoning text arrives in these deltas before the content deltas. |
usage.completion_tokens_details.reasoning_tokens | How many of completion_tokens were reasoning. |
{
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning": "The clause lets either party terminate for convenience. The notice period is ninety (90) days and the notice must be written. One sentence.",
"content": "You need to give 90 days' written notice."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 58,
"completion_tokens": 44,
"total_tokens": 102,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 32 }
}
}reasoning is a SubQ field, so the SDK types don't declare it. Read it like this:
Show reasoning to your users or log it for debugging, but parse only content as the answer.
Messages
Each message has a role and, usually, content.
| Field | Type | Required | Description |
|---|---|---|---|
role | string | Yes | One of system, user, assistant, or tool. |
content | string or content part[] | Yes, except on an assistant message with tool_calls | Message text as a plain string, or an array of content parts. |
Use system for durable instructions, user for user input, assistant for prior model responses (including messages that contain tool_calls), and tool for tool result messages already produced by your application. See Function calling.
The simplest content shape is a string:
{
"role": "user",
"content": "Summarize this release note."
}You can also send text content parts:
{
"role": "user",
"content": [
{ "type": "text", "text": "Summarize this release note." }
]
}For document input, send a text instruction and one or more file parts in the same user message:
{
"role": "user",
"content": [
{ "type": "text", "text": "Summarize these documents." },
{
"type": "file",
"filename": "financial-report-2026.pdf",
"mime_type": "application/pdf",
"file_data": "JVBERi0xLjcKJdDUxdgK..."
},
{
"type": "file",
"filename": "meeting-notes.txt",
"mime_type": "text/plain",
"file_data": "U3ViUSBkb2N1bWVudCBub3Rlcy4uLg=="
}
]
}Document file parts accept inline base64 (file_data) or an uploaded file_id, set directly on the part. A nested file object is not accepted. Audio, video, URL-based file inputs, and other content part types are rejected. See Sending files for file part examples. For the Responses API, use input_file with file_id instead — see Uploaded files.
Images
Send an image as an image_url part holding a base64 data URI, next to a text part that says what to do with it:
{
"role": "user",
"content": [
{ "type": "text", "text": "What is the total due on this invoice?" },
{
"type": "image_url",
"image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." }
}
]
}Image URLs are not supported: an http or https URL returns 400 validation_error. The Responses API ignores image parts, so send images through Chat Completions.
Uploaded files (file_id)
Upload the document with the Files API, wait until
status is processed, then pass its id on a file part:
{
"model": "subq-savant-1.4",
"messages": [{
"role": "user",
"content": [
{ "type": "text", "text": "Summarize this report." },
{ "type": "file", "file_id": "file_abc123" }
]
}]
}An unknown id, or a file owned by another organization, returns 404
file_not_found. A file that hasn't finished processing returns 409
file_not_ready; retry once status is processed. See
Sending files for SDK examples.
Metadata
Attach up to 16 key-value string pairs to a request for your own tracking: run IDs, experiment names, customer tags. SubQ does not act on these values, and the model never sees them.
- Keys can be at most 64 characters; values at most 512 characters.
- Values must be strings. Numbers and booleans are coerced to strings; objects, arrays, and other non-string values are rejected with a
400validation_error. - Omit
metadata, or passnullor{}, for no metadata — all three are treated the same.
{
"model": "subq-savant-1.4",
"messages": [{ "role": "user", "content": "Summarize this release note." }],
"metadata": { "run_id": "eval-2026-08-31-014", "experiment": "reasoning-ablation" }
}A non-streaming response echoes metadata back verbatim:
{
"id": "chatcmpl-mhw3k9zq_4f7k2a",
"metadata": { "run_id": "eval-2026-08-31-014", "experiment": "reasoning-ablation" }
}Streaming chunks do not include metadata.
Storage
By default SubQ stores each request and response under the data-retention policy. Set store: false to keep a single request, including any inline files, out of storage:
{
"model": "subq-savant-1.4",
"messages": [{ "role": "user", "content": "Summarize this patient intake note." }],
"store": false
}Files you reference by file_id stay available. To control exactly when a
document is deleted, upload it with the Files API, pass
its file_id, and delete the file when
you're done.
Request examples
Use cURL for direct HTTP calls, or use the official OpenAI SDK with SubQ's base URL.
Response
A non-streaming request returns a JSON object with the OpenAI-compatible chat completion shape.
{
"id": "chatcmpl-mhw3k9zq_4f7k2a",
"object": "chat.completion",
"created": 1784314379,
"model": "subq-savant-1.4",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "* **Indemnification** is a contractual obligation where one party agrees to compensate the other for losses, damages, or legal costs arising from third-party claims (such as intellectual property infringement or data breaches), effectively shifting the financial risk of those specific external liabilities to the responsible party.\n* **Limitation of Liability** caps the maximum amount of damages one party can be forced to pay the other for breach of contract or negligence, often excluding consequential or indirect damages, thereby protecting both sides from catastrophic financial exposure beyond a predefined threshold (e.g., fees paid in the prior 12 months).\n* **Insurance Requirements** mandate that one or both parties maintain specific types and minimum amounts of insurance coverage (such as general liability, professional liability, or cyber insurance) to ensure there are financial resources available to cover potential claims, serving as a verification of financial capacity rather than a direct transfer of risk between the contracting parties.",
"reasoning": "The user wants three bullets, one per term, in a software-contract setting. Indemnification: who pays for third-party claims. Limitation of liability: a cap on damages between the parties. Insurance requirements: proof there is money behind the promises. Keep each bullet to one sentence and stay practical."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 110,
"completion_tokens": 253,
"total_tokens": 363,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 65 }
}
}Response fields
| Field | Type | Description |
|---|---|---|
id | string | Unique completion ID. |
object | string | Object type. Non-streaming responses use chat.completion. |
created | integer | Unix timestamp, in seconds, for when the completion was created. |
model | string | Model ID used for the completion. |
choices | array | Generated choices. SubQ returns at least one choice for a successful request. |
usage | object | Token usage for the request. |
metadata | object | Echo of the request's metadata, or {} if none was sent. Omitted on streaming chunks. See Metadata. |
Choice fields
| Field | Type | Description |
|---|---|---|
index | integer | Choice index. |
message.role | string | Role of the returned message, usually assistant. |
message.content | string or null | Generated text. null when the model returns tool calls, or when max_tokens was consumed before the answer began—see Token limits. |
message.reasoning | string or null | The model's reasoning, separate from the answer. See Reasoning output. |
message.tool_calls | array | Present when the model requests function calls. See Function calling. |
finish_reason | string | Reason generation stopped. Common values include stop, length (hit max_tokens or the remaining window), and tool_calls. Handle unknown string values defensively. |
Usage fields
| Field | Type | Description |
|---|---|---|
prompt_tokens | integer | Tokens counted from the request messages. Billed at the input rate. |
prompt_tokens_details.cached_tokens | integer | How many of prompt_tokens were served from cache. Billed at the cached input rate. |
completion_tokens | integer | Tokens generated in the response, including any reasoning tokens. Billed at the output rate. |
completion_tokens_details.reasoning_tokens | integer | How many of completion_tokens were reasoning. |
total_tokens | integer | Sum of prompt and completion tokens. |
See Models for the rates.
Errors
Errors use the OpenAI-compatible error shape. param is present when the error traces to one request field.
{
"error": {
"message": "logprobs is not supported for this model.",
"type": "invalid_request_error",
"code": "unsupported_parameter",
"param": "logprobs"
}
}Use code for programmatic handling — message text may change.
| HTTP | code | Meaning |
|---|---|---|
| 400 | validation_error | The body is malformed or a field has an invalid value. |
| 400 | unsupported_value | The request set temperature to a value other than 1, or tried to turn reasoning off. See Restricted parameters. |
| 400 | unsupported_parameter | The request set a parameter SubQ doesn't support. param names it. |
| 400 | context_length_exceeded | The messages plus max_tokens exceed the context window. Shorten the messages or lower max_tokens. |
| 400, 413, 422 | model_rejected_request | The model could not process the request. Check the field named in param. |
| 401 | invalid_api_key | The API key is missing or invalid. |
| 402 | insufficient_credits | The organization is out of credits. |
| 403 | model_not_allowed | The model is not enabled for your organization. See SubQ Savant. |
| 429 | rate_limit_exceeded | Your organization hit a rate limit. Retry with backoff. |
| 429 | model_rejected_request | The model is receiving too many requests. Retry shortly. |
| 502 | model_backend_unavailable, model_backend_error, upstream_error | The model is temporarily unavailable. Retry with backoff. |
| 503 | authorization_failed | Key lookup temporarily unavailable. Retry. |
| 504 | model_backend_timeout | The model did not respond in time. Retry with backoff. |
| 529 | model_overloaded | The service is temporarily overloaded. Retry with backoff. |
A streaming request that fails after the first chunk closes the connection without an error event. Treat a stream that ends before data: [DONE] as failed.