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

# Create chat completion

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/v1/chat/completions`
- Auth: HTTP bearer

Creates a model response from a Chat Completions request. Supported request formats are listed in each model’s details. Unknown fields are accepted on a best-effort basis; model-specific support is not guaranteed.

## Headers

- `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official'

## Request body

- ChatCompletionRequest
  - `model` string, required: ID of the model to use (e.g., gpt-5.4, claude-sonnet-4-6)
  - `messages` ChatMessage[], required: A list of messages comprising the conversation
    - `role` 'system' | 'user' | 'assistant' | 'function' | 'tool' | 'developer', required: The role of the message author
    - `content` union: Message content (text or multimodal)
      - string
      - union[]
        - union
          - object
            - `type` 'text', required
            - `text` string, required
          - object
            - `type` 'image_url', required
            - `image_url` object, required
              - …
          - object
            - `type` 'video_url', required
            - `video_url` object, required
              - …
          - object
            - `type` 'input_audio', required
            - `input_audio` object, required
              - …
    - `name` string: Name of the function/tool (for function/tool messages)
    - `tool_calls` ToolCall[]: Tool calls made by the assistant
      - `id` string, required: Tool call ID
      - `type` 'function', required
      - `function` object, required
        - `name` string, required
        - `arguments` string, required
    - `tool_call_id` string: ID of the tool call being responded to
    - `reasoning_details` object[]: Assistant messages only: the reasoning_details returned in an earlier response, sent back unchanged.
  - `temperature` number: Sampling temperature (0-2)
  - `top_p` number: Nucleus sampling probability
  - `n` integer: Number of completions to generate
  - `stream` boolean: If true, returns a stream of events
  - `stop` union: Stop sequences
    - string
    - string[]
  - `max_tokens` integer: Maximum number of tokens to generate
  - `max_completion_tokens` integer: Maximum completion tokens for newer reasoning-enabled model families
  - `presence_penalty` number: Presence penalty (-2 to 2)
  - `frequency_penalty` number: Frequency penalty (-2 to 2)
  - `tools` Tool[]: List of tools the model may call
    - `type` 'function', required: Tool type (currently only 'function')
    - `function` FunctionDefinition, required
      - `name` string, required: Function name
      - `description` string: Function description
      - `parameters` object: JSON Schema for function parameters
  - `functions` object[]: Deprecated function definitions retained by the official Chat Completions contract.
  - `function_call` union: Deprecated function-call selection retained by the official Chat Completions contract.
    - string
    - object
  - `tool_choice` union: Controls which function is called
    - 'none' | 'auto' | 'required'
    - object
      - `type` 'function', required
      - `function` object, required
        - `name` string, required
  - `response_format` object: Response format specification
    - `type` 'text' | 'json_object'
  - `seed` integer: Seed for deterministic generation
  - `user` string: End-user identifier for abuse detection
  - `stream_options` object: Streaming options such as usage chunk inclusion.
  - `parallel_tool_calls` boolean: Whether the model may issue parallel tool calls.
  - `reasoning_effort` string: Reasoning effort hint for compatible model families.
  - `logprobs` boolean: Whether to return log probabilities for output tokens.
  - `top_logprobs` integer: Number of most likely tokens to return at each position when logprobs is enabled.
  - `logit_bias` object: Per-token logit bias map.
  - `modalities` string[]: Requested output modalities such as text or audio.
  - `audio` object: Audio output configuration when requesting audio modality.
  - `translation_options` object: Language settings for models that translate audio or video through Chat Completions.
    - `source_lang` string: Source language code. Omit when the model supports automatic detection.
    - `target_lang` string, required: Target language code.
  - `prediction` object: Prediction hints for models that support draft or speculative decoding.
  - `service_tier` string, nullable: TokenLab serves this request at the standard service tier. auto and default are forwarded. Other values, such as flex, priority, fast and ultrafast, are ignored and billed at the standard price.
  - `anthropic_options` object: Options for Claude models.
    - `prompt_caching` boolean: Set true to cache the start of the prompt on Claude models. TokenLab marks the end of the system prompt and the latest user message as cache points, unless a message already has cache_control.
    - `prompt_caching_ttl` '5m' | '1h': Cache lifetime. Defaults to 5m. If the serving route does not support 1h, the 5-minute cache is used and the request is not rejected.
  - `extra` object: Extension options. extra.prompt_caching and extra.prompt_caching_ttl are the same as the anthropic_options fields.
    - `prompt_caching` boolean: Set true to cache the start of the prompt on Claude models. TokenLab marks the end of the system prompt and the latest user message as cache points, unless a message already has cache_control.
    - `prompt_caching_ttl` '5m' | '1h': Cache lifetime. Defaults to 5m. If the serving route does not support 1h, the 5-minute cache is used and the request is not rejected.

## Response `200`

Successful response

- ChatCompletionResponse
  - `id` string, required: Unique identifier for the completion
  - `object` 'chat.completion', required: Object type
  - `created` integer, required: Unix timestamp of creation
  - `model` string, required: Model used for completion
  - `choices` ChatChoice[], required
    - `index` integer, required: Choice index
    - `message` object, required
      - `role` 'assistant'
      - `content` string, nullable
      - `tool_calls` ToolCall[]
        - `id` string, required: Tool call ID
        - `type` 'function', required
        - `function` object, required
          - `name` string, required
          - `arguments` string, required
      - `refusal` string, nullable
      - `reasoning_content` string: Thinking text, when the model thinks. Some models return only a summary, or no text.
      - `reasoning_details` object[]: Thinking blocks with their signatures. To continue a conversation with thinking, send them back unchanged in the assistant message.
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter', nullable, required: Reason for completion
  - `usage` UsageInfo
    - `prompt_tokens` integer: Tokens in the prompt
    - `completion_tokens` integer: Tokens in the completion
    - `total_tokens` integer: Total tokens used
    - `prompt_tokens_details` object
      - `cached_tokens` integer
      - `audio_tokens` integer
    - `completion_tokens_details` object
      - `reasoning_tokens` integer
      - `audio_tokens` integer
  - `system_fingerprint` string: System fingerprint

## Other responses

- `400`: Bad Request - Invalid input
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment Required - Insufficient balance or quota exceeded
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error
- `502`: Service Error
- `503`: The requested Delivery tier is temporarily unavailable.

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)