Chat Completions

Create a chat completion by sending a conversation (a list of messages) to a model. The API is fully compatible with the OpenAI Chat Completions format, so you can use existing OpenAI SDKs and tools by changing the base URL.

Endpoint

POST https://api.dos.ai/v1/chat/completions

Authentication

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer dos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys can be created and managed from the dashboard.

Request Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Default	Description
model	string	Yes	-	The model ID to use. See Available Models.
messages	array	Yes	-	A list of messages comprising the conversation. See Message Format.
temperature	number	No	1.0	Sampling temperature between 0 and 2. Lower values produce more focused output; higher values increase randomness.
max_tokens	integer	No	Model default	Maximum number of tokens to generate in the response.
top_p	number	No	1.0	Nucleus sampling parameter. Only tokens within the top top_p probability mass are considered.
stream	boolean	No	false	If true, the response is streamed back as Server-Sent Events (SSE).
stop	string or array	No	null	Up to 4 sequences where the model will stop generating further tokens.
tools	array	No	null	A list of tool (function) definitions the model may call. See Tool Calling.
tool_choice	string or object	No	"auto"	Controls which tool the model calls: "auto", "none", or a specific function.
response_format	object	No	null	Force a specific output format. Use {"type": "json_object"} for JSON mode.
frequency_penalty	number	No	0	Penalizes new tokens based on their frequency in the text so far (-2.0 to 2.0).
presence_penalty	number	No	0	Penalizes new tokens based on whether they appear in the text so far (-2.0 to 2.0).
n	integer	No	1	Number of completions to generate for each prompt.

Message Format

Each message in the messages array is an object with the following fields:

Field	Type	Required	Description
role	string	Yes	One of system, user, assistant, or tool.
content	string	Yes	The text content of the message.
name	string	No	An optional name for the participant.
tool_calls	array	No	Tool calls generated by the model (for assistant messages).
tool_call_id	string	No	The ID of the tool call this message responds to (for tool messages).

Response Body

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711000000,
  "model": "dos-ai",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the completion.
object	string	Always "chat.completion".
created	integer	Unix timestamp of when the completion was created.
model	string	The model used for the completion.
choices	array	A list of completion choices.
choices[].index	integer	The index of this choice in the list.
choices[].message	object	The generated message.
choices[].finish_reason	string	Why the model stopped: "stop", "length", "tool_calls", or "content_filter".
usage	object	Token usage statistics for the request.
usage.prompt_tokens	integer	Number of tokens in the input prompt.
usage.completion_tokens	integer	Number of tokens in the generated response.
usage.total_tokens	integer	Total tokens (prompt + completion).

Streaming

When stream: true is set, the response is delivered as Server-Sent Events (SSE). Each event contains a JSON chunk:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21}}

data: [DONE]

• Each data: line contains a JSON object with a delta field instead of message.
• The delta contains incremental content as it is generated.
• The final chunk includes finish_reason and usage statistics.
• The stream ends with data: [DONE].

Tool Calling

You can provide tool (function) definitions that the model can choose to call. This enables agentic workflows where the model can request external actions.

Defining Tools

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]
}

Tool Call Response

When the model decides to call a tool, the response will have finish_reason: "tool_calls" and include tool call details in the message:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"San Francisco, CA\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Error Responses

Status Code	Error	Description
400	Bad Request	Invalid request parameters.
401	Unauthorized	Invalid or missing API key.
402	Payment Required	Insufficient credits.
429	Too Many Requests	Rate limit exceeded. See Rate Limits.
500	Internal Server Error	Unexpected server error.
503	Service Unavailable	Model temporarily unavailable.

See Error Codes for detailed troubleshooting.

Examples

Basic Chat Completion (cURL)

curl https://api.dos.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "dos-ai",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

Streaming (cURL)

curl https://api.dos.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -N \
  -d '{
    "model": "dos-ai",
    "messages": [
      {"role": "user", "content": "Write a haiku about programming."}
    ],
    "stream": true
  }'

Using the OpenAI Python SDK

Since DOS AI is OpenAI-compatible, you can use the official OpenAI SDK by changing the base URL:

from openai import OpenAI

client = OpenAI(
    api_key="dos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://api.dos.ai/v1"
)

response = client.chat.completions.create(
    model="dos-ai",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ],
    temperature=0.7,
    max_tokens=512
)

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

Using the OpenAI Node.js SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "dos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  baseURL: "https://api.dos.ai/v1",
});

const response = await client.chat.completions.create({
  model: "dos-ai",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain quantum computing in simple terms." },
  ],
  temperature: 0.7,
  max_tokens: 512,
});

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

JSON Mode

curl https://api.dos.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "dos-ai",
    "messages": [
      {"role": "system", "content": "Respond in JSON format."},
      {"role": "user", "content": "List 3 programming languages with their year of creation."}
    ],
    "response_format": {"type": "json_object"}
  }'

Tool Calling Example

curl https://api.dos.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "dos-ai",
    "messages": [
      {"role": "user", "content": "What is the weather in Tokyo?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City name"
              }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'