Chat Completions API

Early access
Copy Page as Markdown

Use 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/completions

Request body

Send a JSON object with the required model and messages fields. Omit optional fields unless you need to change generation behavior.

FieldTypeRequiredDescription
modelstringYesModel ID to use, such as subq-savant-1.4. See Models.
messagesarrayYesConversation messages in order. Must contain at least one message.
streambooleanNoWhen false or omitted, returns one JSON response. When true, returns server-sent events.
temperaturenumberNoFixed at 1. Omit it or send 1. Any other value returns 400 unsupported_value. See Restricted parameters.
max_tokensintegerNoCaps generated tokens. Must be at least 1. See Token limits.
top_pnumberNoNucleus sampling value from 0 to 1.
stopstring or string[]NoUp to 4 sequences where generation stops.
reasoning_effortstringNoHow much the model reasons before answering: low, high (the default), or max. Reasoning cannot be turned off. See Reasoning effort.
response_formatobjectNoConstrain the assistant reply to a JSON Schema. See Structured outputs.
toolsarrayNoFunction tools the model may call. See Function calling.
tool_choicestringNoWhether the model may call tools: "auto" (the default) or "none". See Tool choice.
storeboolean or nullNoSet false to keep this request and response out of storage. Defaults to true. See Storage.
metadataobject or nullNoUp 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.

ParameterRulecode
temperatureFixed at 1. Omit it or send 1.unsupported_value
reasoning_effortnone 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 200 with content set to null and finish_reason of "length": billed, with nothing visible.
  • Input and output share the 4M-token context window. If the input plus max_tokens cannot fit, the API returns 400 context_length_exceeded.
  • Send max_tokens, not max_completion_tokens.
  • The minimum is 1. If omitted, the response can use all remaining context.
  • If generation hits the cap, choices[0].finish_reason is "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
}
cURLTypeScriptPython

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.

ValueUse it for
lowShort answers, extraction, and latency-sensitive requests.
highThe default. Most analysis, drafting, and agent loops.
maxHard 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_tokens and counted in max_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"
}
cURLTypeScriptPython

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.

FieldContains
choices[0].message.reasoningThe reasoning text. null if the response has no reasoning text.
choices[0].delta.reasoningWhen streaming, reasoning text arrives in these deltas before the content deltas.
usage.completion_tokens_details.reasoning_tokensHow 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:

TypeScriptPython

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.

FieldTypeRequiredDescription
rolestringYesOne of system, user, assistant, or tool.
contentstring or content part[]Yes, except on an assistant message with tool_callsMessage 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 400 validation_error.
  • Omit metadata, or pass null or {}, 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.

cURLTypeScriptPython

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

FieldTypeDescription
idstringUnique completion ID.
objectstringObject type. Non-streaming responses use chat.completion.
createdintegerUnix timestamp, in seconds, for when the completion was created.
modelstringModel ID used for the completion.
choicesarrayGenerated choices. SubQ returns at least one choice for a successful request.
usageobjectToken usage for the request.
metadataobjectEcho of the request's metadata, or {} if none was sent. Omitted on streaming chunks. See Metadata.

Choice fields

FieldTypeDescription
indexintegerChoice index.
message.rolestringRole of the returned message, usually assistant.
message.contentstring or nullGenerated text. null when the model returns tool calls, or when max_tokens was consumed before the answer began—see Token limits.
message.reasoningstring or nullThe model's reasoning, separate from the answer. See Reasoning output.
message.tool_callsarrayPresent when the model requests function calls. See Function calling.
finish_reasonstringReason generation stopped. Common values include stop, length (hit max_tokens or the remaining window), and tool_calls. Handle unknown string values defensively.

Usage fields

FieldTypeDescription
prompt_tokensintegerTokens counted from the request messages. Billed at the input rate.
prompt_tokens_details.cached_tokensintegerHow many of prompt_tokens were served from cache. Billed at the cached input rate.
completion_tokensintegerTokens generated in the response, including any reasoning tokens. Billed at the output rate.
completion_tokens_details.reasoning_tokensintegerHow many of completion_tokens were reasoning.
total_tokensintegerSum 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.

HTTPcodeMeaning
400validation_errorThe body is malformed or a field has an invalid value.
400unsupported_valueThe request set temperature to a value other than 1, or tried to turn reasoning off. See Restricted parameters.
400unsupported_parameterThe request set a parameter SubQ doesn't support. param names it.
400context_length_exceededThe messages plus max_tokens exceed the context window. Shorten the messages or lower max_tokens.
400, 413, 422model_rejected_requestThe model could not process the request. Check the field named in param.
401invalid_api_keyThe API key is missing or invalid.
402insufficient_creditsThe organization is out of credits.
403model_not_allowedThe model is not enabled for your organization. See SubQ Savant.
429rate_limit_exceededYour organization hit a rate limit. Retry with backoff.
429model_rejected_requestThe model is receiving too many requests. Retry shortly.
502model_backend_unavailable, model_backend_error, upstream_errorThe model is temporarily unavailable. Retry with backoff.
503authorization_failedKey lookup temporarily unavailable. Retry.
504model_backend_timeoutThe model did not respond in time. Retry with backoff.
529model_overloadedThe 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.