> For the complete documentation index, see [llms.txt](https://docs.arcee.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arcee.ai/api-reference/chat-completion.md). # 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."}}}} ```