Chat Completions API

Use the Chat Completions API to generate a response from SubQ for a list of conversation messages.

POST /v1/chat/completions

All requests must include a valid API key in the Authorization header. See Authentication for details.

Request 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-preview. 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	Sampling temperature from 0 to 2. Higher values make output more random.
max_tokens	integer	No	Maximum number of tokens to generate. Must be at least 1.
top_p	number	No	Nucleus sampling value from 0 to 1. Use this or temperature, not both, for most requests.
stop	string or string[]	No	Stop sequence or sequences where generation should stop.

This page documents the non-streaming response. For a non-streaming request, omit stream or set it to false.

Messages

Each message has a role and content.

Field	Type	Required	Description
role	string	Yes	One of system, user, assistant, or tool.
content	string or text part[]	Yes	Message text, either as a plain string or an array of text content parts.

Use system for durable instructions, user for user input, assistant for prior model responses, and tool for tool result messages already produced by your application.

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." }
  ]
}

Only text content parts are supported. Image, audio, file, and other content part types are rejected.

Request examples

Use cURL for direct HTTP calls, or use the official OpenAI SDK with SubQ’s base URL.

cURL Node.js TypeScript Python Copy

curl --request POST \
  --url https://api.subq.ai/v1/chat/completions \
  --header 'Authorization: Bearer $SUBQ_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "subq-preview",
  "messages": [
    {
      "role": "system",
      "content": "You are concise and practical."
    },
    {
      "role": "user",
      "content": "Explain what SubQ is good for."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 500
}
'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SUBQ_API_KEY,
  baseURL: "https://api.subq.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "subq-preview",
  messages: [
    {
      role: "system",
      content: "You are concise and practical."
    },
    {
      role: "user",
      content: "Explain what SubQ is good for."
    }
  ],
  temperature: 0.2,
  max_tokens: 500
});

console.log(completion.choices[0]?.message?.content);

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SUBQ_API_KEY,
  baseURL: "https://api.subq.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "subq-preview",
  messages: [
    {
      role: "system",
      content: "You are concise and practical."
    },
    {
      role: "user",
      content: "Explain what SubQ is good for."
    }
  ],
  temperature: 0.2,
  max_tokens: 500
});

console.log(completion.choices[0]?.message?.content);

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUBQ_API_KEY"],
    base_url="https://api.subq.ai/v1",
)

completion = client.chat.completions.create(
    model="subq-preview",
    messages=[
        {
            "role": "system",
            "content": "You are concise and practical.",
        },
        {
            "role": "user",
            "content": "Explain what SubQ is good for.",
        },
    ],
    temperature=0.2,
    max_tokens=500,
)

print(completion.choices[0].message.content)

Response

A non-streaming request returns a JSON object with the OpenAI-compatible chat completion shape.

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1768000000,
  "model": "subq-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Use SubQ for long-context chat completion requests through the SubQ API."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 27,
    "total_tokens": 58
  }
}

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.

Choice fields

Field	Type	Description
index	integer	Choice index.
message.role	string	Role of the returned message, usually assistant.
message.content	string	Generated text.
finish_reason	string	Reason generation stopped. Common values include stop and length; handle unknown string values defensively.

Usage fields

Field	Type	Description
prompt_tokens	integer	Tokens counted from the request messages.
completion_tokens	integer	Tokens generated in the response.
total_tokens	integer	Sum of prompt and completion tokens.