---
title: "Create a chat completion"
method: POST
path: "/v1/chat/completions"
tags: ["Chat Completions"]
---

# Create a chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.arcee.ai`
- URL: `https://api.arcee.ai/v1/chat/completions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/arcee/apis/arcee-chat-completions-api/docs/v1/chat/completions/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- object
  - `model` string, required
  - `messages` union[]
    - union
      - ChatCompletionSystemMessageParam
        - `content` string, required
        - `role` 'system', required
        - `name` string
      - ChatCompletionUserMessageParam
        - `content` union, required
          - string
          - union[]
            - union
              - …
        - `role` 'user', required
        - `name` string
      - ChatCompletionAssistantMessageParam
        - `role` 'assistant', required
        - `content` string, nullable
        - `function_call` FunctionCall
          - `arguments` string, required
          - `name` string, required
        - `name` string
        - `tool_calls` ChatCompletionMessageToolCallParam[]
          - `id` string, required
          - `function` Function, required
            - `arguments` string, required
            - `name` string, required
          - `type` 'function', required
      - ChatCompletionFunctionMessageParam
        - `content` union, required
          - string
          - union[]
            - union
              - …
        - `name` string, required
        - `role` 'function', required
      - ChatCompletionToolMessageParam
        - `content` union, required
          - string
          - union[]
            - union
              - …
        - `role` 'tool', required
        - `tool_call_id` string, required
  - `timeout` union
    - number
    - integer
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `n` integer, nullable
  - `stream` boolean, nullable
  - `stop` object, nullable
  - `max_tokens` integer, nullable
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `logit_bias` object, nullable
  - `user` string, nullable
  - `seed` integer, nullable
  - `tools` Tool[]: A list of tools the model may call. Currently only function tools are supported.
    - `type` 'function', required
    - `function` object, required
      - `name` string, required: Name of the function to be called.
      - `description` string: Description of what the function does.
      - `parameters` object: JSON Schema object describing the function's parameters.
  - `tool_choice` 'auto' | 'none' | 'required': 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` boolean, nullable
  - `top_logprobs` integer, nullable
  - `functions` string[], nullable
  - `function_call` string, nullable

## Response `200`

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`.

- ChatCompletionResponse: OpenAI-compatible chat completion response. Standard fields (`id`, `object`, `created`, `model`, `choices`, `usage`) are returned; provider-specific extras are stripped before responding.

## Other responses

- `400`: Invalid Format
- `401`: Authentication Fails
- `402`: Insufficient Balance
- `403`: Permission Denied
- `404`: Not Found
- `422`: Invalid Parameters
- `429`: Rate Limit Reached
- `500`: Server Error
- `503`: Server Overloaded

---

[API](https://skmtc.dev/arcee/apis/arcee-chat-completions-api.md) - [All operations](https://skmtc.dev/arcee/apis/arcee-chat-completions-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arcee/apis/arcee-chat-completions-api/revisions/66e6d99d47bc?raw)