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

# Create a chat completion

`POST /api/{workspaceID}/v1/chat/completions`

## Request

- Base URL: `https://ai.liara.ir`
- URL: `https://ai.liara.ir/api/{workspaceID}/v1/chat/completions`
- Auth: API key in header `Authorization`

Creates a model response for the given conversation. Supports streaming via SSE,
tool calling, and multi-modal input (text, images, files).

## Path parameters

- `workspaceID` string, required

## Request body

- ChatCompletionRequest
  - `model` string, required: Model ID
  - `messages` ChatMessage[], required: Array of conversation messages
    - `role` 'user' | 'assistant' | 'system' | 'developer' | 'tool', required
    - `content` union
      - string
      - ContentPart[]
        - union
          - object: Text content
            - `type` 'text', required
            - `text` string, required
          - object: Image URL content
            - `type` 'image_url', required
            - `image_url` object, required
              - …
          - object: File content
            - `type` 'file', required
            - `file` object, required
              - …
    - `name` string: Name of the participant
    - `tool_calls` object[]: Tool calls made by the assistant
    - `tool_call_id` string: ID of the tool call this message responds to
    - `refusal` string: Refusal message from the assistant
  - `stream` boolean: Enable SSE streaming
  - `stream_options` object
    - `include_usage` boolean: Include usage stats in streaming response
  - `max_tokens` integer: Maximum tokens to generate
  - `max_completion_tokens` integer: Maximum completion tokens (OpenAI-style)
  - `temperature` number: Sampling temperature (0-2)
  - `top_p` number: Nucleus sampling parameter
  - `top_k` number: Top-K sampling parameter
  - `frequency_penalty` number: Frequency penalty (-2 to 2)
  - `presence_penalty` number: Presence penalty (-2 to 2)
  - `repetition_penalty` number: Repetition penalty
  - `seed` integer: Random seed for deterministic output
  - `n` integer: Number of completions to generate
  - `stop` union: Stop sequences
    - string
    - string[]
  - `logit_bias` object: Token ID to bias mapping
  - `logprobs` boolean: Return log probabilities
  - `top_logprobs` integer: Number of top log probabilities to return
  - `min_p` number: Minimum probability parameter
  - `top_a` number: Top-A sampling parameter
  - `reasoning` object: Reasoning configuration
  - `reasoning_effort` string: Reasoning effort level
  - `modalities` string[]: Output modalities
  - `functions` object[]: Legacy function definitions
  - `tools` object[]: Tool definitions for function calling
  - `tool_choice` union
    - 'none' | 'auto' | 'required'
    - object
      - `type` 'function'
      - `function` object
        - `name` string
  - `parallel_tool_calls` boolean: Allow parallel tool calls
  - `response_format` object: Response format specification
  - `prediction` object: Predicted output for latency optimization
  - `metadata` unknown
  - `store` boolean: Store the completion
  - `service_tier` string: Service tier
  - `user` string: End-user identifier

## Response `200`

Successful response (non-streaming)

- ChatCompletionResponse
  - `id` string: Log ID
  - `model` string: Model ID used
  - `object` 'chat.completion'
  - `created` integer
  - `choices` object[]
    - `index` integer
    - `message` ChatMessage
      - `role` 'user' | 'assistant' | 'system' | 'developer' | 'tool', required
      - `content` union
        - string
        - ContentPart[]
          - union
            - object: Text content
              - …
            - object: Image URL content
              - …
            - object: File content
              - …
      - `name` string: Name of the participant
      - `tool_calls` object[]: Tool calls made by the assistant
      - `tool_call_id` string: ID of the tool call this message responds to
      - `refusal` string: Refusal message from the assistant
    - `finish_reason` string
  - `usage` object
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `total_cost_toman` number
    - `total_cost` number

## Other responses

- `400`: Bad request
- `401`: Missing authentication
- `402`: Payment required - insufficient balance
- `403`: Forbidden - workspace frozen or key disabled
- `503`: Service temporarily unavailable.

---

[API](https://skmtc.dev/liara-cloud/apis/ai-chat-completions.md) - [All operations](https://skmtc.dev/liara-cloud/apis/ai-chat-completions/llms.txt) - [OpenAPI document](https://skmtc.dev/liara-cloud/apis/ai-chat-completions/revisions/c34e1fe0a4a3?raw)