# Chat Completion

## POST /v1/chat/completions

> Create a chat completion

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"servers":[{"url":"https://api.arcee.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Arcee API key (prefixed with `rcai-`)"}},"schemas":{"ChatCompletionSystemMessageParam":{"properties":{"content":{"title":"Content","type":"string"},"role":{"const":"system","title":"Role","type":"string"},"name":{"title":"Name","type":"string"}},"required":["content","role"],"title":"ChatCompletionSystemMessageParam","type":"object"},"ChatCompletionUserMessageParam":{"properties":{"content":{"anyOf":[{"type":"string"},{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartTextParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartImageParam"}]},"type":"array"}],"title":"Content"},"role":{"const":"user","title":"Role","type":"string"},"name":{"title":"Name","type":"string"}},"required":["content","role"],"title":"ChatCompletionUserMessageParam","type":"object"},"ChatCompletionContentPartTextParam":{"properties":{"text":{"title":"Text","type":"string"},"type":{"const":"text","title":"Type","type":"string"}},"required":["text","type"],"title":"ChatCompletionContentPartTextParam","type":"object"},"ChatCompletionContentPartImageParam":{"properties":{"image_url":{"$ref":"#/components/schemas/ImageURL"},"type":{"const":"image_url","title":"Type","type":"string"}},"required":["image_url","type"],"title":"ChatCompletionContentPartImageParam","type":"object"},"ImageURL":{"properties":{"url":{"title":"Url","type":"string"},"detail":{"enum":["auto","low","high"],"title":"Detail","type":"string"}},"required":["url"],"title":"ImageURL","type":"object"},"ChatCompletionAssistantMessageParam":{"properties":{"role":{"const":"assistant","title":"Role","type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"function_call":{"$ref":"#/components/schemas/FunctionCall"},"name":{"title":"Name","type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/ChatCompletionMessageToolCallParam"},"title":"Tool Calls","type":"array"}},"required":["role"],"title":"ChatCompletionAssistantMessageParam","type":"object"},"FunctionCall":{"properties":{"arguments":{"title":"Arguments","type":"string"},"name":{"title":"Name","type":"string"}},"required":["arguments","name"],"title":"FunctionCall","type":"object"},"ChatCompletionMessageToolCallParam":{"properties":{"id":{"title":"Id","type":"string"},"function":{"$ref":"#/components/schemas/Function"},"type":{"const":"function","title":"Type","type":"string"}},"required":["id","function","type"],"title":"ChatCompletionMessageToolCallParam","type":"object"},"Function":{"properties":{"arguments":{"title":"Arguments","type":"string"},"name":{"title":"Name","type":"string"}},"required":["arguments","name"],"title":"Function","type":"object"},"ChatCompletionFunctionMessageParam":{"properties":{"content":{"anyOf":[{"type":"string"},{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartTextParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartImageParam"}]},"type":"array"}],"title":"Content"},"name":{"title":"Name","type":"string"},"role":{"const":"function","title":"Role","type":"string"}},"required":["content","name","role"],"title":"ChatCompletionFunctionMessageParam","type":"object"},"ChatCompletionToolMessageParam":{"properties":{"content":{"anyOf":[{"type":"string"},{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartTextParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartImageParam"}]},"type":"array"}],"title":"Content"},"role":{"const":"tool","title":"Role","type":"string"},"tool_call_id":{"title":"Tool Call Id","type":"string"}},"required":["content","role","tool_call_id"],"title":"ChatCompletionToolMessageParam","type":"object"},"Tool":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the function to be called."},"description":{"type":"string","description":"Description of what the function does."},"parameters":{"type":"object","description":"JSON Schema object describing the function's parameters."}}}}},"ChatCompletionResponse":{"type":"object","description":"OpenAI-compatible chat completion response. Standard fields (`id`, `object`, `created`, `model`, `choices`, `usage`) are returned; provider-specific extras are stripped before responding."},"Error":{"type":"object","properties":{"detail":{"type":"string","description":"Human-readable error message."}},"required":["detail"]}}},"paths":{"/v1/chat/completions":{"post":{"summary":"Create a chat completion","operationId":"createChatCompletion","tags":["Chat Completions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"model":{"title":"Model","type":"string"},"messages":{"default":[],"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionSystemMessageParam"},{"$ref":"#/components/schemas/ChatCompletionUserMessageParam"},{"$ref":"#/components/schemas/ChatCompletionAssistantMessageParam"},{"$ref":"#/components/schemas/ChatCompletionFunctionMessageParam"},{"$ref":"#/components/schemas/ChatCompletionToolMessageParam"}]},"title":"Messages","type":"array"},"timeout":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"default":null,"title":"Timeout"},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Temperature"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Top P"},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"N"},"stream":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Stream"},"stop":{"anyOf":[{"type":"object"},{"type":"null"}],"default":null,"title":"Stop"},"max_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Max Tokens"},"presence_penalty":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Presence Penalty"},"frequency_penalty":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Frequency Penalty"},"logit_bias":{"anyOf":[{"type":"object"},{"type":"null"}],"default":null,"title":"Logit Bias"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Seed"},"tools":{"type":"array","description":"A list of tools the model may call. Currently only function tools are supported.","items":{"$ref":"#/components/schemas/Tool"}},"tool_choice":{"type":"string","enum":["auto","none","required"],"description":"Controls whether the model calls a tool. `auto` lets the model decide, `none` disables tool calls, `required` forces the model to call a tool."},"logprobs":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Logprobs"},"top_logprobs":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Top Logprobs"},"functions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Functions"},"function_call":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Function Call"}},"required":["model"],"title":"CompletionRequest","type":"object"}}}},"responses":{"200":{"description":"Chat completion result. When `stream: true`, the response is returned as `text/event-stream` instead of JSON, with OpenAI-style `data: {chunk}\\n\\n` framing terminated by `data: [DONE]\\n\\n`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}}}},"400":{"description":"Invalid Format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication Fails","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission Denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid Parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Server Overloaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## The ChatCompletionContentPartImageParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionContentPartImageParam":{"properties":{"image_url":{"$ref":"#/components/schemas/ImageURL"},"type":{"const":"image_url","title":"Type","type":"string"}},"required":["image_url","type"],"title":"ChatCompletionContentPartImageParam","type":"object"},"ImageURL":{"properties":{"url":{"title":"Url","type":"string"},"detail":{"enum":["auto","low","high"],"title":"Detail","type":"string"}},"required":["url"],"title":"ImageURL","type":"object"}}}}
```

## The ChatCompletionAssistantMessageParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionAssistantMessageParam":{"properties":{"role":{"const":"assistant","title":"Role","type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"function_call":{"$ref":"#/components/schemas/FunctionCall"},"name":{"title":"Name","type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/ChatCompletionMessageToolCallParam"},"title":"Tool Calls","type":"array"}},"required":["role"],"title":"ChatCompletionAssistantMessageParam","type":"object"},"FunctionCall":{"properties":{"arguments":{"title":"Arguments","type":"string"},"name":{"title":"Name","type":"string"}},"required":["arguments","name"],"title":"FunctionCall","type":"object"},"ChatCompletionMessageToolCallParam":{"properties":{"id":{"title":"Id","type":"string"},"function":{"$ref":"#/components/schemas/Function"},"type":{"const":"function","title":"Type","type":"string"}},"required":["id","function","type"],"title":"ChatCompletionMessageToolCallParam","type":"object"},"Function":{"properties":{"arguments":{"title":"Arguments","type":"string"},"name":{"title":"Name","type":"string"}},"required":["arguments","name"],"title":"Function","type":"object"}}}}
```

## The ChatCompletionContentPartTextParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionContentPartTextParam":{"properties":{"text":{"title":"Text","type":"string"},"type":{"const":"text","title":"Type","type":"string"}},"required":["text","type"],"title":"ChatCompletionContentPartTextParam","type":"object"}}}}
```

## The ChatCompletionFunctionMessageParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionFunctionMessageParam":{"properties":{"content":{"anyOf":[{"type":"string"},{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartTextParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartImageParam"}]},"type":"array"}],"title":"Content"},"name":{"title":"Name","type":"string"},"role":{"const":"function","title":"Role","type":"string"}},"required":["content","name","role"],"title":"ChatCompletionFunctionMessageParam","type":"object"},"ChatCompletionContentPartTextParam":{"properties":{"text":{"title":"Text","type":"string"},"type":{"const":"text","title":"Type","type":"string"}},"required":["text","type"],"title":"ChatCompletionContentPartTextParam","type":"object"},"ChatCompletionContentPartImageParam":{"properties":{"image_url":{"$ref":"#/components/schemas/ImageURL"},"type":{"const":"image_url","title":"Type","type":"string"}},"required":["image_url","type"],"title":"ChatCompletionContentPartImageParam","type":"object"},"ImageURL":{"properties":{"url":{"title":"Url","type":"string"},"detail":{"enum":["auto","low","high"],"title":"Detail","type":"string"}},"required":["url"],"title":"ImageURL","type":"object"}}}}
```

## The ChatCompletionMessageToolCallParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionMessageToolCallParam":{"properties":{"id":{"title":"Id","type":"string"},"function":{"$ref":"#/components/schemas/Function"},"type":{"const":"function","title":"Type","type":"string"}},"required":["id","function","type"],"title":"ChatCompletionMessageToolCallParam","type":"object"},"Function":{"properties":{"arguments":{"title":"Arguments","type":"string"},"name":{"title":"Name","type":"string"}},"required":["arguments","name"],"title":"Function","type":"object"}}}}
```

## The ChatCompletionSystemMessageParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionSystemMessageParam":{"properties":{"content":{"title":"Content","type":"string"},"role":{"const":"system","title":"Role","type":"string"},"name":{"title":"Name","type":"string"}},"required":["content","role"],"title":"ChatCompletionSystemMessageParam","type":"object"}}}}
```

## The ChatCompletionToolMessageParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionToolMessageParam":{"properties":{"content":{"anyOf":[{"type":"string"},{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartTextParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartImageParam"}]},"type":"array"}],"title":"Content"},"role":{"const":"tool","title":"Role","type":"string"},"tool_call_id":{"title":"Tool Call Id","type":"string"}},"required":["content","role","tool_call_id"],"title":"ChatCompletionToolMessageParam","type":"object"},"ChatCompletionContentPartTextParam":{"properties":{"text":{"title":"Text","type":"string"},"type":{"const":"text","title":"Type","type":"string"}},"required":["text","type"],"title":"ChatCompletionContentPartTextParam","type":"object"},"ChatCompletionContentPartImageParam":{"properties":{"image_url":{"$ref":"#/components/schemas/ImageURL"},"type":{"const":"image_url","title":"Type","type":"string"}},"required":["image_url","type"],"title":"ChatCompletionContentPartImageParam","type":"object"},"ImageURL":{"properties":{"url":{"title":"Url","type":"string"},"detail":{"enum":["auto","low","high"],"title":"Detail","type":"string"}},"required":["url"],"title":"ImageURL","type":"object"}}}}
```

## The ChatCompletionUserMessageParam object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionUserMessageParam":{"properties":{"content":{"anyOf":[{"type":"string"},{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartTextParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartImageParam"}]},"type":"array"}],"title":"Content"},"role":{"const":"user","title":"Role","type":"string"},"name":{"title":"Name","type":"string"}},"required":["content","role"],"title":"ChatCompletionUserMessageParam","type":"object"},"ChatCompletionContentPartTextParam":{"properties":{"text":{"title":"Text","type":"string"},"type":{"const":"text","title":"Type","type":"string"}},"required":["text","type"],"title":"ChatCompletionContentPartTextParam","type":"object"},"ChatCompletionContentPartImageParam":{"properties":{"image_url":{"$ref":"#/components/schemas/ImageURL"},"type":{"const":"image_url","title":"Type","type":"string"}},"required":["image_url","type"],"title":"ChatCompletionContentPartImageParam","type":"object"},"ImageURL":{"properties":{"url":{"title":"Url","type":"string"},"detail":{"enum":["auto","low","high"],"title":"Detail","type":"string"}},"required":["url"],"title":"ImageURL","type":"object"}}}}
```

## The Function object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"Function":{"properties":{"arguments":{"title":"Arguments","type":"string"},"name":{"title":"Name","type":"string"}},"required":["arguments","name"],"title":"Function","type":"object"}}}}
```

## The FunctionCall object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"FunctionCall":{"properties":{"arguments":{"title":"Arguments","type":"string"},"name":{"title":"Name","type":"string"}},"required":["arguments","name"],"title":"FunctionCall","type":"object"}}}}
```

## The ImageURL object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ImageURL":{"properties":{"url":{"title":"Url","type":"string"},"detail":{"enum":["auto","low","high"],"title":"Detail","type":"string"}},"required":["url"],"title":"ImageURL","type":"object"}}}}
```

## The Tool object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"Tool":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the function to be called."},"description":{"type":"string","description":"Description of what the function does."},"parameters":{"type":"object","description":"JSON Schema object describing the function's parameters."}}}}}}}}
```

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"detail":{"type":"string","description":"Human-readable error message."}},"required":["detail"]}}}}
```

## The ChatCompletionResponse object

```json
{"openapi":"3.1.0","info":{"title":"Arcee Chat Completions API","version":"1.0.0"},"components":{"schemas":{"ChatCompletionResponse":{"type":"object","description":"OpenAI-compatible chat completion response. Standard fields (`id`, `object`, `created`, `model`, `choices`, `usage`) are returned; provider-specific extras are stripped before responding."}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.arcee.ai/api-reference/chat-completion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.