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

# Create chat completion

`POST /chat/completions`

Generate a model response for a given chat conversation. Supports single queries and multi-turn conversations with system, user, and assistant messages.

## Request body

- ChatCompletionRequest
  - `messages` ChatCompletionMessageParam[], required — A list of messages comprising the conversation so far.
    - union
      - ChatCompletionSystemMessageParam
        - `content` string, required
        - `role` 'system', required
        - `name` string
      - ChatCompletionUserMessageParam
        - `content` union, required — The content of the message, which can either be a simple string or a structured format.
          - string — A plain text message.
          - union[] — A structured message with mixed content types.
            - union
              - …
        - `role` 'user', required
        - `name` string
      - ChatCompletionAssistantMessageParam
        - `content` string, nullable
        - `role` 'assistant', required
        - `name` string
        - `tool_calls` ToolChoice[]
          - `index` number, required
          - `id` string, required
          - `type` 'function', required
          - `function` object, required
            - `name` string, required
            - `arguments` string, required
        - `function_call` object
          - `arguments` string, required
          - `name` string, required
        - `reasoning` string, nullable
        - `reasoning_content` string, nullable
      - ChatCompletionToolMessageParam
        - `name` string
        - `role` 'tool', required
        - `content` string, required
        - `tool_call_id` string, required
      - ChatCompletionFunctionMessageParam
        - `role` 'function', required
        - `content` string, required
        - `name` string, required
  - `model` string, required — The name of the model to query.<br> <br> [See all of Together AI's chat models](https://docs.together.ai/docs/serverless-models#chat-models)
  - `max_tokens` integer — The maximum number of tokens to generate.
  - `stop` string[] — A list of string sequences that truncate (stop) inference text output. For example, "</s>" stops generation as soon as the model generates the given token.
  - `temperature` number — A decimal number from 0-1 that determines the degree of randomness in the response. A temperature less than 1 favors more correctness and is appropriate for question answering or summarization. A value closer to 1 introduces more randomness in the output.
  - `top_p` number — A percentage (also called the nucleus parameter) that's used to dynamically adjust the number of choices for each predicted token based on the cumulative probabilities. It specifies a probability threshold below which all less likely tokens are filtered out. This technique helps maintain diversity and generate more fluent and natural-sounding text.
  - `top_k` integer — An integer that's used to limit the number of choices for the next predicted word or token. It specifies the maximum number of tokens to consider at each step, based on their probability of occurrence. This technique helps to speed up the generation process and can improve the quality of the generated text by focusing on the most likely options.
  - `context_length_exceeded_behavior` 'truncate' | 'error' — Defines the behavior of the API when max_tokens exceed the maximum context length of the model. When set to 'error', the API returns 400 with an appropriate error message. When set to 'truncate', overrides max_tokens with the maximum context length of the model.
  - `repetition_penalty` number — A number that controls the diversity of generated text by reducing the likelihood of repeated sequences. Higher values decrease repetition.
  - `stream` boolean — If true, stream tokens as Server-Sent Events as the model generates them instead of waiting for the full model response. The stream terminates with `data: [DONE]`. If false, return a single JSON object containing the results.
  - `logprobs` integer — An integer between 0 and 20 of the top k tokens to return log probabilities for at each generation step, instead of only the sampled token. Log probabilities help assess model confidence in token predictions.
  - `echo` boolean — If true, the response contains the prompt. Can be used with `logprobs` to return prompt logprobs.
  - `n` integer — The number of completions to generate for each prompt.
  - `min_p` number — A number between 0 and 1 that can be used as an alternative to top_p and top-k.
  - `presence_penalty` number — A number between -2.0 and 2.0 where a positive value increases the likelihood of a model talking about new topics.
  - `frequency_penalty` number — A number between -2.0 and 2.0 where a positive value decreases the likelihood of repeating tokens that have already been mentioned.
  - `logit_bias` object — Adjusts the likelihood of specific tokens appearing in the generated output.
  - `seed` integer — Seed value for reproducibility.
  - `function_call` union
    - 'none' | 'auto'
    - object
      - `name` string, required
  - `response_format` union — An object specifying the format that the model must output. Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://docs.together.ai/docs/json-mode). Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it.
    - ResponseFormatText — Default response format. Used to generate text responses.
      - `type` 'text', required — The type of response format being defined. Always `text`.
    - ResponseFormatJsonSchema — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://docs.together.ai/docs/json-mode).
      - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`.
      - `json_schema` object, required — Structured Outputs configuration options, including a JSON Schema.
        - `description` string — A description of what the response format is for, used by the model to determine how to respond in the format.
        - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        - `schema` ResponseFormatJsonSchemaSchema — The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/).
        - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](https://docs.together.ai/docs/json-mode).
    - ResponseFormatJsonObject — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.
      - `type` 'json_object', required — The type of response format being defined. Always `json_object`.
  - `tools` ToolsPart[] — A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.
    - `type` string
    - `function` object
      - `description` string
      - `name` string
      - `parameters` object — A map of parameter names to their values.
  - `tool_choice` union — Controls which (if any) function is called by the model. By default uses `auto`, which lets the model pick between generating a message or calling a function.
    - string
    - ToolChoice
      - `index` number, required
      - `id` string, required
      - `type` 'function', required
      - `function` object, required
        - `name` string, required
        - `arguments` string, required
  - `compliance` 'hipaa'
  - `chat_template_kwargs` object — Additional configuration to pass to model engine.
  - `safety_model` string — The name of the moderation model used to validate tokens. Choose from the available moderation models found [here](https://docs.together.ai/docs/inference-models#moderation-models).
  - `reasoning_effort` 'low' | 'medium' | 'high' — Controls the level of reasoning effort the model should apply when generating responses. Higher values may result in more thoughtful and detailed responses but may take longer to generate.
  - `reasoning` object — For models that support toggling reasoning functionality, this object can be used to control that functionality.
    - `enabled` boolean

## Response `200`

200

- ChatCompletionResponse
  - `id` string, required
  - `choices` object[], required
    - `text` string
    - `index` integer
    - `seed` integer
    - `finish_reason` 'stop' | 'eos' | 'length' | 'tool_calls' | 'function_call'
    - `message` ChatCompletionMessage
      - `content` string, nullable, required
      - `role` 'assistant', required
      - `tool_calls` ToolChoice[]
        - `index` number, required
        - `id` string, required
        - `type` 'function', required
        - `function` object, required
          - `name` string, required
          - `arguments` string, required
      - `function_call` object
        - `arguments` string, required
        - `name` string, required
      - `reasoning` string, nullable
      - `reasoning_content` string, nullable
    - `logprobs` object, nullable
      - `token_ids` number[] — List of token IDs corresponding to the logprobs
      - `tokens` string[] — List of token strings
      - `token_logprobs` number[] — List of token log probabilities
      - `top_logprobs` TopLogprobs — Top log probabilities for the tokens.
    - `top_logprobs` TopLogprobs — Top log probabilities for the tokens.
  - `usage` UsageData, nullable
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
  - `created` integer, required
  - `model` string, required
  - `prompt` object[], required
    - `text` string
    - `logprobs` LogprobsPart
      - `token_ids` number[] — List of token IDs corresponding to the logprobs
      - `tokens` string[] — List of token strings
      - `token_logprobs` number[] — List of token log probabilities
      - `top_logprobs` TopLogprobs — Top log probabilities for the tokens.
  - `object` 'chat.completion', required — The object type, which is always `chat.completion`.
  - `warnings` InferenceWarning[]
    - `message` string, required

## Other responses

- `400` — BadRequest
- `401` — Unauthorized
- `404` — NotFound
- `429` — RateLimit
- `503` — Overloaded
- `504` — Timeout

---

[API](https://skmtc.net/together/apis/together-apis.md) · [All operations](https://skmtc.net/together/apis/together-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/together/together-apis/revisions/468edbdc879c/schema)