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

# Chat Completions

`POST /v1/chat/completions`

## Request

- Base URL: `https://apipie.ai`
- URL: `https://apipie.ai/v1/chat/completions`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Query LLM using text and, for vision-capable models, image data. This endpoint supports multiple models (up to 5, comma-separated) in the model field. Specify the appropriate request format depending on whether the model is text-based or vision-capable.

An array of responses: will be returned for multi-model queries.

Please refer to the ChatCompletionRequest for text-based models and VisionChatCompletionRequest for vision-capable models for detailed request formats.

## Request body

- union
  - ChatCompletionRequest
    - `messages` ChatCompletionMessage[], required
      - `role` 'assistant' | 'system' | 'user': Message role
      - `content` string: Content of the message
    - `user` string: Unique identifier for the user, enabling tenant observability for usage and billing, and providing tenant services for memory and inline_cli.
    - `inline_cli` string: Command to enable or disable inline CLI features. Can be boolean true/false or a comma-delimited string of features like all, disabled, information, integrity, memory, model, search, shaping. send :help in your prompt for more details
    - `model` string, required: Language Model to use, comma separated, up to 5 models. Check our /models route for list of language models. Cannot use provider option with multi-model.
    - `provider` string: AI Service Provider to use, omit provider and we will automatically use the most responsive provider. Optionally you can include provider with the model instead such as model: provider/model
    - `vector_provider` 'pinecone' | 'qdrant': Vector provider to use to store memory and rag tune data, make sure to use the same provider per collection/session.
    - `memory` true | false: Enable Integrated Model Memory to maintain conversation context. Set to true to enable memory for this conversation, the default is false.
    - `mem_session` string: Optional unique identifier for maintaining separate memory chains for different users/applications. If not provided, a default session is used.
    - `mem_expire` integer: Optional time in minutes after which stored memories will automatically expire and be deleted.
    - `mem_clear` 0 | 1: Set to 1 to instantly delete all stored memories for the specified mem_session.
    - `mem_msgs` integer: Maximum number of messages to append from memory to the user provided prompts. The default is 8 additional messages
    - `mem_length` integer: Percentage (1-100) of model's max response tokens to use for memory. For example, 20 on a 100k max response tokens model would allow up to 20k tokens for memory augmentation. The default is 20%
    - `shortMem` integer: Number of recent user–assistant message pairs to keep in short-term memory (state cache). Each pair equals 2 messages. Max: 10 pairs (20 messages). Default: 3.
    - `longMem` integer: Number of individual messages to retrieve from long-term memory (vector similarity search). Max: 10 messages. Default: 2.
    - `rag_tune` string: Specify the name of the rag tune or vector collection to be used for RAG tuning. This will augment the language model query with information from the specified vector database.
    - `routing` string: Define how we should route your call when you do not specify a provider and multiple providers exist for that model. Options are price (cheapest), multi-tiered performance (routing based on lowest latency for prompt size) and average_latency. The default is perf (price/perf/perf_avg)
    - `temperature` number: Influences the randomness in the selection process of the next token. Lower values make the model more deterministic, while higher values increase diversity but might reduce coherence.
    - `top_p` number: Controls the cumulative probability distribution cutoff, selecting the smallest set of tokens whose cumulative probability exceeds the threshold p. This focuses generation on more likely tokens, enhancing creativity and coherence.
    - `top_k` integer: Limits the selection pool to the top k most probable tokens. The probability distribution is then reranked among these k tokens, which helps in reducing randomness by eliminating the least likely options.
    - `frequency_penalty` number: Adjusts the likelihood of a token's selection based on its previous occurrences, decreasing the chances of frequently selected tokens to promote diversity in the output.
    - `presence_penalty` number: Similar to frequency penalty, but it decreases the likelihood of tokens appearing again based on their presence, regardless of frequency, to encourage novel token selection.
    - `repetition_penalty` number: Discourages the model from repeating the same words or phrases, enhancing the uniqueness and variety of the content generated.
    - `n` integer: receive this many responses to your prompt, currently only works with OpenAI direct
    - `beam_size` integer: Used in beam search, it represents the number of sequences to keep at each step of the generation. A larger beam size increases the chances of finding a more optimal sequence but at the cost of computational resources and time. Only some models support this
    - `search_whitelist` string[]: Array of root FQDNs to allow for AI search (e.g., ["apnews.com", "bbc.com", "reuters.com"]). If not provided/null, AI can use any URLs that searches present. Applies to all search-augmented completions. Backward compatible: strings (comma-delimited) are also accepted and will be converted to arrays.
    - `search_blacklist` string[]: Array of root FQDNs to block for AI search (e.g., ["cnn.com", "foxnews.com"]). If not provided/null, no URLs are blocked. Applies to all search-augmented completions. Backward compatible: strings (comma-delimited) are also accepted and will be converted to arrays.
    - `web_search_options` object: Options for web search context size using Valyu search provider. Controls the amount of search content provided to the model. Defaults to low.
      - `search_context_size` 'low' | 'medium' | 'high': - low: 1 search query, 1 result per query - medium: 2 search queries, 2 results per query (4 total contents) - high: 4 search queries, 2 results per query (8 total contents)
    - `search_provider` 'valyu' | 'google': Search provider to use for inline internet augmentation. Can be "valyu" or "google". Default is "valyu".
    - `search_lang` string: Language code for search results, e.g., en for English.
    - `search_geo` string: Geographical code for search results, e.g., US for United States.
    - `max_tokens` integer: Max tokens used to generate a response
    - `stream` boolean: Return response in event-stream
    - `stream_errors` boolean: Controls how errors are returned when using streaming responses. Defaults to true. - If true (default), all streaming error messages are sent in the message body, which is commonly used for browser clients. - If false, errors are thrown and not streamed in the response body. This may not be as comprehensive in some cases where the error happens after the stream starts.
    - `tools` object[]: Optional tools/functions, all models support tools, serviced by an Open AI or Anthropic model of your choice. Function calls are handled in Open AI standard request/response format.
      - `type` 'function'
      - `function` object
        - `name` string: Name of the function to call
        - `description` string: Description of the function
        - `parameters` object: Parameters required by the function
    - `tool_choice` string: Specifies how the tools are chosen. "none" means the model will not call any tool and instead generates a message, this is default. "auto" means the model can pick between generating a message or calling one or more tools, this is how most devs use it. "required" means the model must call one or more tools.
    - `tools_model` string: Specifies the model to use for processing tools, pass any OpenAI or Anthropic model, gpt-4o-mini is default.
    - `integrity` 12 | 13: Integrity setting, can be 12 or 13, used to query and return best of two answers or the best of 3 answers.
    - `integrity_model` string: Specifies model to use for integrity checks, currently only supports OpenAI models.
    - `force_provider` boolean: Force request to be routed to the specified provider, otherwise request will be routed to the requested provider only if it is available
  - VisionChatCompletionRequest
    - `model` string, required: Vision Model to use, refer to /models route for compatible vision models
    - `messages` VisionChatCompletionMessage[], required
      - `role` 'user': Role of the message sender
      - `content` union[]
        - union
          - object
            - `type` 'text'
            - `text` string: Textual content of the message
          - object
            - `type` 'image_url'
            - `image_url` object
              - …
    - `max_tokens` integer: Max tokens used to generate a response

## Response `200`

Result of the Query

- ChatCompletionResponse
  - `id` string, required: Unique identifier for the completion.
  - `object` string, required: Type of the returned object, usually set to chat.completion.
  - `created` integer, required: UTC timestamp of when the completion was created.
  - `provider` string, required: Provider of the AI service.
  - `model` string, required: AI model used for generating the completion.
  - `choices` object[], required: Array of possible completion options generated by the model.
    - `index` integer, required: Index of the choice in the array.
    - `message` object, required
      - `role` string: Role of the message, such as user or assistant.
      - `content` string: Content of the message.
    - `logprobs` object, nullable: Log probabilities for the completion, can be null.
    - `finish_reason` string, required: Reason why the model stopped generating text.
  - `search_length` integer: Character count augmented to the prompt by the search.
  - `search_latency_ms` integer: Latency in milliseconds added by the search and processing.
  - `usage` object, required
    - `prompt_tokens` integer, required: Number of tokens used in the prompt.
    - `completion_tokens` integer, required: Number of tokens generated in the completion.
    - `total_tokens` integer, required: Total number of tokens used in both prompt and completion.
    - `prompt_characters` integer, required: Number of characters used in the prompt.
    - `response_characters` integer, required: Number of characters in the response.
    - `cost` number, float, required: Cost associated with the computation of the completion.
    - `latency_ms` integer, required: Latency in milliseconds for the completion to be generated.
  - `system_fingerprint` string, required: Unique fingerprint of the system configuration used.
  - `streaming` object: Object detailing streaming data chunks if stream is true.
    - `type` string: Type of the streamed object, usually chat.completion.chunk.
    - `chunks` object[]: Array of data chunks streamed.
      - `content` string: Content of the streamed data chunk.
      - `index` integer: Index of the data chunk in the stream.
      - `finish_reason` string: Reason for the finish of this particular chunk.
      - `usage` string: tokens, characters, latency and cost for this query

---

[API](https://skmtc.dev/apipie/apis/introduction.md) · [All operations](https://skmtc.dev/apipie/apis/introduction/llms.txt) · [OpenAPI document](https://skmtc.dev/apipie/apis/introduction/revisions/f8386be4eb3f?raw)