---
title: "POST /chat/completions"
method: POST
path: "/chat/completions"
tags: ["ChatCompletion"]
---

# POST /chat/completions

`POST /chat/completions`

Generate a chat completion for the given messages using the specified model.

## Request body

- CreateChatCompletionRequest
  - `model` string, required — The identifier of the model to use.
  - `messages` Message[], required — List of messages in the conversation.
    - union
      - UserMessage — A message from the user in a chat conversation.
        - `role` 'user', required — Must be "user" to identify this as a user message.
        - `content` union, required — The content of the user message, which can include text and other media.
          - string — The text contents of the message.
          - UserMessageContentItem[] — A list of content items, which can include text and other media. Supported content types differ based on model.
            - union
              - …
      - SystemMessage — A system message providing instructions or context to the model.
        - `role` 'system', required — Must be "system" to identify this as a system message
        - `content` union, required — The content of the system message.
          - string — The text contents of the message.
          - MessageTextContentItem[] — A list of content items, which can include text and other media. Supported content types differ based on model.
            - `type` 'text', required — Discriminator type of the content item. Always "text"
            - `text` string, required — Text content
      - ToolResponseMessage — A message representing the result of a tool invocation.
        - `role` 'tool', required — Must be "tool" to identify this as a tool response
        - `tool_call_id` string, required — Unique identifier for the tool call this response is for
        - `content` union, required — The content of the user message, which can include text and other media.
          - string — The text contents of the message.
          - MessageTextContentItem[] — A list of content items, which can include text and other media. Supported content types differ based on model.
            - `type` 'text', required — Discriminator type of the content item. Always "text"
            - `text` string, required — Text content
      - AssistantMessage — A message containing the model's (assistant) response in a chat conversation.
        - `role` 'assistant', required — Must be "assistant" to identify this as the model's response
        - `content` union — The content of the model's response.
          - string
          - AssistantMessageContentItem — A text content item
            - `type` 'text', required — Discriminator type of the content item. Always "text"
            - `text` string, required — Text content
        - `stop_reason` 'stop' | 'tool_calls' | 'length' — The reason why we stopped. Options are: - "stop": The model reached a natural stopping point. - "tool_calls": The model finished generating and invoked a tool call. - "length": The model reached the maxinum number of tokens specified in the request.
        - `tool_calls` MessageToolCall[] — The tool calls generated by the model, such as function calls.
          - `id` string, required — The ID of the tool call.
          - `function` object, required — The function that the model called.
            - `name` string, required — The name of the function to call.
            - `arguments` string, required — The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.
  - `tools` ChatCompletionTool[] — List of tool definitions available to the model
    - `type` 'function', required — The type of the tool. Currently, only `function` is supported.
    - `function` FunctionObject, required
      - `description` string — A description of what the function does, used by the model to choose when and how to call the function.
      - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
      - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. Omitting `parameters` defines a function with an empty parameter list.
      - `strict` boolean — Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](docs/guides/function-calling).
  - `tool_choice` union — Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present.
    - 'none' | 'auto' | 'required' — `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.
    - ChatCompletionNamedToolChoice — Specifies a tool the model should use. Use to force the model to call a specific function.
      - `type` 'function', required — The type of the tool. Currently, only `function` is supported.
      - `function` object, required
        - `name` string, required — The name of the function to call.
  - `response_format` union
    - object — Configuration for JSON schema-guided response generation.
      - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`.
      - `json_schema` object, required — The JSON schema the response should conform to.
        - `name` string, required — The name of the response format.
        - `schema` JsonSchemaResponseFormatSchema, required — The JSON schema the response should conform to. In a Python SDK, this is often a `pydantic` model.
    - object — Configuration for text-guided response generation.
      - `type` 'text', required — The type of response format being defined. Always `text`.
  - `stream` boolean — If True, generate an SSE event stream of the response. Defaults to False.
  - `repetition_penalty` number — Controls the likelyhood and generating repetitive responses.
  - `temperature` number — Controls randomness of the response by setting a temperature. Higher value leads to more creative responses. Lower values will make the response more focused and deterministic.
  - `top_p` number — Controls diversity of the response by setting a probability threshold when choosing the next token.
  - `top_k` integer — Only sample from the top K options for each subsequent token.
  - `max_completion_tokens` integer — The maximum number of tokens to generate.
  - `user` string — A unique identifier representing your application end-user for monitoring abuse.

## Response `200`

If stream=False, returns a CreateChatCompletionResponse with the full completion. If stream=True, returns an SSE event stream of CreateChatCompletionResponseStreamChunk

- CreateChatCompletionResponse — Response from a chat completion request.
  - `id` string — The unique identifier of the chat completion request.
  - `metrics` MetricInResponse[]
    - `metric` string, required
    - `value` union, required
      - integer
      - number
    - `unit` string
  - `completion_message` AssistantMessage, required — A message containing the model's (assistant) response in a chat conversation.
    - `role` 'assistant', required — Must be "assistant" to identify this as the model's response
    - `content` union — The content of the model's response.
      - string
      - AssistantMessageContentItem — A text content item
        - `type` 'text', required — Discriminator type of the content item. Always "text"
        - `text` string, required — Text content
    - `stop_reason` 'stop' | 'tool_calls' | 'length' — The reason why we stopped. Options are: - "stop": The model reached a natural stopping point. - "tool_calls": The model finished generating and invoked a tool call. - "length": The model reached the maxinum number of tokens specified in the request.
    - `tool_calls` MessageToolCall[] — The tool calls generated by the model, such as function calls.
      - `id` string, required — The ID of the tool call.
      - `function` object, required — The function that the model called.
        - `name` string, required — The name of the function to call.
        - `arguments` string, required — The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

## Other responses

- `400` — The request was invalid or malformed
- `429` — The client has sent too many requests in a given amount of time
- `500` — The server encountered an unexpected error
- `default` — An unexpected error occurred

---

[API](https://skmtc.dev/meta-llama/apis/llama-api-specification.md) · [All operations](https://skmtc.dev/meta-llama/apis/llama-api-specification/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/meta-llama/llama-api-specification/revisions/edf0a308dd29/schema)