---
title: "Create Chat Completion"
method: POST
path: "/chat/completions"
---

# Create Chat Completion

`POST /chat/completions`

Generate a chat completion response for the given conversation.

## Request body

- ApiChatCompletionsRequest
  - `max_tokens` integer, nullable
  - `temperature` number, nullable
  - `top_k` integer, nullable
  - `top_p` number, nullable
  - `n` integer, nullable
  - `presence_penalty` number, nullable
  - `frequency_penalty` number, nullable
  - `model` string, required
  - `stream` boolean, nullable
  - `stop` union
    - string
    - string[]
  - `cum_logprobs` boolean, nullable
  - `logprobs` boolean, nullable
  - `top_logprobs` integer, nullable
  - `best_of` integer, nullable
  - `response_metadata` object, nullable
  - `response_format` union
    - ResponseFormatText
      - `type` 'text', required
    - ResponseFormatJSONSchema
      - `type` 'json_schema', required
      - `json_schema` JSONSchema, required
        - `schema` object, required
        - `name` string, nullable
        - `description` string, nullable
        - `strict` boolean, nullable
    - ResponseFormatRegex
      - `type` 'regex', required
      - `regex` RegexSchema, required
        - `regex` string, required
        - `name` string, nullable
        - `description` string, nullable
        - `strict` boolean, nullable
  - `diverse_first_token` boolean, nullable
  - `_inputs` integer[], nullable
  - `_prompt_token_length` integer, nullable
  - `messages` ChatMessageInput[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool', required — Chat roles enum
    - `content` union, required
      - string
      - union[]
        - union
          - ChatMessageContentTextChunk
            - `type` 'text', required
            - `text` string, required
          - ChatMessageContentImageChunk
            - `type` 'image_url', required
            - `image_url` union, required
              - …
          - ChatMessageContentFileChunk
            - `type` 'file_url', required
            - `file_url` union, required
              - …
            - `file_name` string, nullable
          - ChatMessageContentPDFChunk
            - `type` 'pdf_url', required
            - `pdf_url` union, required
              - …
          - ChatMessageContentVideoChunk
            - `type` 'video_url', required
            - `video_url` union, required
              - …
    - `reasoning_steps` ReasoningStepInput[], nullable
      - `thought` string, required
      - `type` string, nullable
      - `web_search` WebSearchStepDetails — Web search step details wrapper class
        - `search_results` ApiPublicSearchResult[], required
          - `title` string, required
          - `url` string, required
          - `date` string, nullable
          - `last_updated` string, nullable
          - `snippet` string
          - `source` 'web' | 'attachment'
        - `search_keywords` string[], required
      - `fetch_url_content` FetchUrlContentStepDetails — Fetch url content step details wrapper class
        - `contents` ApiPublicSearchResult[], required
          - `title` string, required
          - `url` string, required
          - `date` string, nullable
          - `last_updated` string, nullable
          - `snippet` string
          - `source` 'web' | 'attachment'
      - `execute_python` ExecutePythonStepDetails — Code generation step details wrapper class
        - `code` string, required
        - `result` string, required
    - `tool_calls` ToolCall[], nullable
      - `id` string, nullable
      - `type` 'function', nullable
      - `function` ToolCallFunction
        - `name` string, nullable
        - `arguments` string, nullable
    - `tool_call_id` string, nullable
  - `tools` ToolSpec[], nullable
    - `type` 'function', required
    - `function` FunctionSpec, required
      - `name` string, required
      - `description` string, required
      - `parameters` ParameterSpec, required
        - `type` string, required
        - `properties` object, required
        - `required` string[], nullable
        - `additional_properties` boolean, nullable
      - `strict` boolean, nullable
  - `tool_choice` 'none' | 'auto' | 'required', nullable
  - `parallel_tool_calls` boolean, nullable
  - `web_search_options` WebSearchOptions
    - `search_context_size` 'low' | 'medium' | 'high'
    - `search_type` 'fast' | 'pro' | 'auto', nullable
    - `user_location` UserLocation
      - `latitude` number, nullable
      - `longitude` number, nullable
      - `country` string, nullable
      - `city` string, nullable
      - `region` string, nullable
    - `image_results_enhanced_relevance` boolean
  - `search_mode` 'web' | 'academic' | 'sec', nullable
  - `return_images` boolean, nullable
  - `return_related_questions` boolean, nullable
  - `num_search_results` integer
  - `num_images` integer
  - `enable_search_classifier` boolean, nullable
  - `disable_search` boolean, nullable
  - `search_domain_filter` string[], nullable
  - `search_language_filter` string[], nullable
  - `search_tenant` string, nullable
  - `ranking_model` string, nullable
  - `latitude` number, nullable
  - `longitude` number, nullable
  - `country` string, nullable
  - `search_recency_filter` 'hour' | 'day' | 'week' | 'month' | 'year', nullable
  - `search_after_date_filter` string, nullable
  - `search_before_date_filter` string, nullable
  - `last_updated_before_filter` string, nullable
  - `last_updated_after_filter` string, nullable
  - `image_format_filter` string[], nullable
  - `image_domain_filter` string[], nullable
  - `safe_search` boolean, nullable
  - `file_workspace_id` string, nullable
  - `updated_before_timestamp` integer, nullable
  - `updated_after_timestamp` integer, nullable
  - `search_internal_properties` object, nullable
  - `use_threads` boolean, nullable
  - `thread_id` string, nullable
  - `stream_mode` 'full' | 'concise'
  - `_debug_pro_search` boolean
  - `has_image_url` boolean
  - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high', nullable
  - `language_preference` string, nullable
  - `user_original_query` string, nullable
  - `_force_new_agent` boolean, nullable
  - `response_formatting_locale` string, nullable — Optional locale tag used for response formatting conventions. Locale-style values such as `es_mx`, `EN-us`, and `zh-TW` are normalized to the canonical form (`es-MX`, `en-US`, `zh-TW`). Invalid values are ignored.

## Response `200`

Successful Response

- CompletionResponse
  - `id` string, required
  - `model` string, required
  - `created` integer, required
  - `usage` UsageInfo
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `search_context_size` string, nullable
    - `citation_tokens` integer, nullable
    - `num_search_queries` integer, nullable
    - `reasoning_tokens` integer, nullable
    - `cost` Cost, required
      - `input_tokens_cost` number, required
      - `output_tokens_cost` number, required
      - `reasoning_tokens_cost` number, nullable
      - `request_cost` number, nullable — Flat request cost for the chat completion. Present on completed (terminal) responses and omitted from the zero cost skeleton on interim streaming chunks.
      - `citation_tokens_cost` number, nullable
      - `search_queries_cost` number, nullable
      - `total_cost` number, required
  - `object` string
  - `choices` Choice[], required
    - `index` integer, required
    - `finish_reason` 'stop' | 'length', nullable
    - `message` ChatMessageOutput, required
      - `role` 'system' | 'user' | 'assistant' | 'tool', required — Chat roles enum
      - `content` union, required
        - string
        - union[]
          - union
            - ChatMessageContentTextChunk
              - …
            - ChatMessageContentImageChunk
              - …
            - ChatMessageContentFileChunk
              - …
            - ChatMessageContentPDFChunk
              - …
            - ChatMessageContentVideoChunk
              - …
      - `reasoning_steps` ReasoningStepOutput[], nullable
        - `thought` string, required
        - `type` string, nullable
        - `web_search` WebSearchStepDetails — Web search step details wrapper class
          - `search_results` ApiPublicSearchResult[], required
            - `title` string, required
            - `url` string, required
            - `date` string, nullable
            - `last_updated` string, nullable
            - `snippet` string
            - `source` 'web' | 'attachment'
          - `search_keywords` string[], required
        - `fetch_url_content` FetchUrlContentStepDetails — Fetch url content step details wrapper class
          - `contents` ApiPublicSearchResult[], required
            - `title` string, required
            - `url` string, required
            - `date` string, nullable
            - `last_updated` string, nullable
            - `snippet` string
            - `source` 'web' | 'attachment'
        - `execute_python` ExecutePythonStepDetails — Code generation step details wrapper class
          - `code` string, required
          - `result` string, required
      - `tool_calls` ToolCall[], nullable
        - `id` string, nullable
        - `type` 'function', nullable
        - `function` ToolCallFunction
          - `name` string, nullable
          - `arguments` string, nullable
      - `tool_call_id` string, nullable
    - `delta` ChatMessageOutput, required
      - `role` 'system' | 'user' | 'assistant' | 'tool', required — Chat roles enum
      - `content` union, required
        - string
        - union[]
          - union
            - ChatMessageContentTextChunk
              - …
            - ChatMessageContentImageChunk
              - …
            - ChatMessageContentFileChunk
              - …
            - ChatMessageContentPDFChunk
              - …
            - ChatMessageContentVideoChunk
              - …
      - `reasoning_steps` ReasoningStepOutput[], nullable
        - `thought` string, required
        - `type` string, nullable
        - `web_search` WebSearchStepDetails — Web search step details wrapper class
          - `search_results` ApiPublicSearchResult[], required
            - `title` string, required
            - `url` string, required
            - `date` string, nullable
            - `last_updated` string, nullable
            - `snippet` string
            - `source` 'web' | 'attachment'
          - `search_keywords` string[], required
        - `fetch_url_content` FetchUrlContentStepDetails — Fetch url content step details wrapper class
          - `contents` ApiPublicSearchResult[], required
            - `title` string, required
            - `url` string, required
            - `date` string, nullable
            - `last_updated` string, nullable
            - `snippet` string
            - `source` 'web' | 'attachment'
        - `execute_python` ExecutePythonStepDetails — Code generation step details wrapper class
          - `code` string, required
          - `result` string, required
      - `tool_calls` ToolCall[], nullable
        - `id` string, nullable
        - `type` 'function', nullable
        - `function` ToolCallFunction
          - `name` string, nullable
          - `arguments` string, nullable
      - `tool_call_id` string, nullable
  - `citations` string[], nullable
  - `search_results` ApiPublicSearchResult[], nullable
    - `title` string, required
    - `url` string, required
    - `date` string, nullable
    - `last_updated` string, nullable
    - `snippet` string
    - `source` 'web' | 'attachment'
  - `type` 'message' | 'info' | 'end_of_stream'
  - `status` 'PENDING' | 'COMPLETED'

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/perplexityai/apis/perplexity-ai-api.md) · [All operations](https://skmtc.net/perplexityai/apis/perplexity-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/perplexityai/perplexity-ai-api/versions/bcca72d3b564/schema)