# 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](https://app.dos.ai). ## 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](https://docs.dos.ai/models/available-models). | | `messages` | array | Yes | - | A list of messages comprising the conversation. See [Message Format](#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-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 ```json { "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 ```json { "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: ```json { "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](https://docs.dos.ai/support/rate-limits). | | 500 | Internal Server Error | Unexpected server error. | | 503 | Service Unavailable | Model temporarily unavailable. | See [Error Codes](https://docs.dos.ai/support/error-codes) for detailed troubleshooting. ## Examples ### Basic Chat Completion (cURL) ```bash 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) ```bash 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: ```python 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 ```javascript 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 ```bash 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 ```bash 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"] } } } ] }' ```