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

# Chat Completions

`POST /openai/chat/completions`

## Request body

- union
  - ChatCompletionNonStreaming
    - `messages` union[], required
      - union
        - ChatCompletionDeveloperMessageParam — Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, `developer` messages replace the previous `system` messages.
          - `content` union, required
            - string
            - ChatCompletionContentPartTextParam[]
              - …
          - `role` 'developer', required
          - `name` string
        - ChatCompletionSystemMessageParam — Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, use `developer` messages for this purpose instead.
          - `content` union, required
            - string
            - ChatCompletionContentPartTextParam[]
              - …
          - `role` 'system', required
          - `name` string
        - ChatCompletionUserMessageParam — Messages sent by an end user, containing prompts or additional context information.
          - `content` union, required
            - string
            - union[]
              - …
          - `role` 'user', required
          - `name` string
        - ChatCompletionAssistantMessageParam — Messages sent by the model in response to user messages.
          - `role` 'assistant', required
          - `audio` Audio — Data about a previous audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).
            - `id` string, required
          - `content` union
            - string
            - union[]
              - …
          - `function_call` FunctionCallInput — Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
            - `arguments` string, required
            - `name` string, required
          - `name` string
          - `refusal` string, nullable
          - `tool_calls` union[]
            - union
              - …
        - ChatCompletionToolMessageParam
          - `content` union, required
            - string
            - ChatCompletionContentPartTextParam[]
              - …
          - `role` 'tool', required
          - `tool_call_id` string, required
        - ChatCompletionFunctionMessageParam
          - `content` string, nullable, required
          - `name` string, required
          - `role` 'function', required
    - `model` union
      - string
      - Model
        - `name` string, required
        - `extra_headers` object, nullable
        - `options` object, nullable
      - object
      - union[]
        - union
          - string
          - Model
            - `name` string, required
            - `extra_headers` object, nullable
            - `options` object, nullable
          - object
    - `audio` ChatCompletionAudioParam — Parameters for audio output. Required when audio output is requested with `modalities: ["audio"]`. [Learn more](https://platform.openai.com/docs/guides/audio).
      - `format` 'wav' | 'aac' | 'mp3' | 'flac' | 'opus' | 'pcm16', required
      - `voice` union, required
        - string
        - 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'sage' | 'shimmer' | 'verse' | 'marin' | 'cedar'
    - `frequency_penalty` number, nullable
    - `function_call` union
      - 'none' | 'auto'
      - ChatCompletionFunctionCallOptionParam — Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
        - `name` string, required
    - `functions` OpenaiTypesChatCompletionCreateParamsFunction[]
      - `name` string, required
      - `description` string
      - `parameters` object
    - `logit_bias` object, nullable
    - `logprobs` boolean, nullable
    - `max_completion_tokens` integer, nullable
    - `max_tokens` integer, nullable
    - `metadata` object, nullable
    - `modalities` string[], nullable
    - `n` integer, nullable
    - `parallel_tool_calls` boolean
    - `prediction` ChatCompletionPredictionContentParam — Static predicted output content, such as the content of a text file that is being regenerated.
      - `content` union, required
        - string
        - ChatCompletionContentPartTextParam[]
          - `text` string, required
          - `type` 'text', required
      - `type` 'content', required
    - `presence_penalty` number, nullable
    - `prompt_cache_key` string
    - `prompt_cache_retention` 'in-memory' | '24h', nullable
    - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `response_format` union
      - ResponseFormatText — Default response format. Used to generate text responses.
        - `type` 'text', required
      - ResponseFormatJSONSchema — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs).
        - `json_schema` JSONSchema, required — Structured Outputs configuration options, including a JSON Schema.
          - `name` string, required
          - `description` string
          - `schema` object
          - `strict` boolean, nullable
        - `type` 'json_schema', required
      - 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
    - `safety_identifier` string
    - `seed` integer, nullable
    - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority', nullable
    - `stop` union
      - string
      - string[]
    - `store` boolean, nullable
    - `stream_options` ChatCompletionStreamOptionsParam — Options for streaming response. Only set this when you set `stream: true`.
      - `include_obfuscation` boolean
      - `include_usage` boolean
    - `temperature` number, nullable
    - `tool_choice` union
      - 'none' | 'auto' | 'required'
      - ChatCompletionAllowedToolChoiceParam — Constrains the tools available to the model to a pre-defined set.
        - `allowed_tools` ChatCompletionAllowedToolsParam, required — Constrains the tools available to the model to a pre-defined set.
          - `mode` 'auto' | 'required', required
          - `tools` object[], required
        - `type` 'allowed_tools', required
      - ChatCompletionNamedToolChoiceParam — Specifies a tool the model should use. Use to force the model to call a specific function.
        - `function` OpenaiTypesChatChatCompletionNamedToolChoiceParamFunction, required
          - `name` string, required
        - `type` 'function', required
      - ChatCompletionNamedToolChoiceCustomParam — Specifies a tool the model should use. Use to force the model to call a specific custom tool.
        - `custom` OpenaiTypesChatChatCompletionNamedToolChoiceCustomParamCustom, required
          - `name` string, required
        - `type` 'custom', required
    - `tools` union[]
      - union
        - ChatCompletionFunctionToolParam — A function tool that can be used to generate a response.
          - `function` FunctionDefinition, required
            - `name` string, required
            - `description` string
            - `parameters` object
            - `strict` boolean, nullable
          - `type` 'function', required
        - ChatCompletionCustomToolParam — A custom tool that processes input using a specified format.
          - `custom` OpenaiTypesChatChatCompletionCustomToolParamCustom, required — Properties of the custom tool.
            - `name` string, required
            - `description` string
            - `format` union
              - …
          - `type` 'custom', required
    - `top_logprobs` integer, nullable
    - `top_p` number, nullable
    - `user` string
    - `verbosity` 'low' | 'medium' | 'high', nullable
    - `web_search_options` WebSearchOptions — This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
      - `search_context_size` 'low' | 'medium' | 'high'
      - `user_location` WebSearchOptionsUserLocation — Approximate location parameters for the search.
        - `approximate` WebSearchOptionsUserLocationApproximate, required — Approximate location parameters for the search.
          - `city` string
          - `country` string
          - `region` string
          - `timezone` string
        - `type` 'approximate', required
    - `stream` false, nullable
    - `tags` object, nullable
    - `parent_span_id` string, uuid, nullable
  - ChatCompletionStreaming
    - `messages` union[], required
      - union
        - ChatCompletionDeveloperMessageParam — Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, `developer` messages replace the previous `system` messages.
          - `content` union, required
            - string
            - ChatCompletionContentPartTextParam[]
              - …
          - `role` 'developer', required
          - `name` string
        - ChatCompletionSystemMessageParam — Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, use `developer` messages for this purpose instead.
          - `content` union, required
            - string
            - ChatCompletionContentPartTextParam[]
              - …
          - `role` 'system', required
          - `name` string
        - ChatCompletionUserMessageParam — Messages sent by an end user, containing prompts or additional context information.
          - `content` union, required
            - string
            - union[]
              - …
          - `role` 'user', required
          - `name` string
        - ChatCompletionAssistantMessageParam — Messages sent by the model in response to user messages.
          - `role` 'assistant', required
          - `audio` Audio — Data about a previous audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).
            - `id` string, required
          - `content` union
            - string
            - union[]
              - …
          - `function_call` FunctionCallInput — Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
            - `arguments` string, required
            - `name` string, required
          - `name` string
          - `refusal` string, nullable
          - `tool_calls` union[]
            - union
              - …
        - ChatCompletionToolMessageParam
          - `content` union, required
            - string
            - ChatCompletionContentPartTextParam[]
              - …
          - `role` 'tool', required
          - `tool_call_id` string, required
        - ChatCompletionFunctionMessageParam
          - `content` string, nullable, required
          - `name` string, required
          - `role` 'function', required
    - `model` union
      - string
      - Model
        - `name` string, required
        - `extra_headers` object, nullable
        - `options` object, nullable
      - object
      - union[]
        - union
          - string
          - Model
            - `name` string, required
            - `extra_headers` object, nullable
            - `options` object, nullable
          - object
    - `audio` ChatCompletionAudioParam — Parameters for audio output. Required when audio output is requested with `modalities: ["audio"]`. [Learn more](https://platform.openai.com/docs/guides/audio).
      - `format` 'wav' | 'aac' | 'mp3' | 'flac' | 'opus' | 'pcm16', required
      - `voice` union, required
        - string
        - 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'sage' | 'shimmer' | 'verse' | 'marin' | 'cedar'
    - `frequency_penalty` number, nullable
    - `function_call` union
      - 'none' | 'auto'
      - ChatCompletionFunctionCallOptionParam — Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
        - `name` string, required
    - `functions` OpenaiTypesChatCompletionCreateParamsFunction[]
      - `name` string, required
      - `description` string
      - `parameters` object
    - `logit_bias` object, nullable
    - `logprobs` boolean, nullable
    - `max_completion_tokens` integer, nullable
    - `max_tokens` integer, nullable
    - `metadata` object, nullable
    - `modalities` string[], nullable
    - `n` integer, nullable
    - `parallel_tool_calls` boolean
    - `prediction` ChatCompletionPredictionContentParam — Static predicted output content, such as the content of a text file that is being regenerated.
      - `content` union, required
        - string
        - ChatCompletionContentPartTextParam[]
          - `text` string, required
          - `type` 'text', required
      - `type` 'content', required
    - `presence_penalty` number, nullable
    - `prompt_cache_key` string
    - `prompt_cache_retention` 'in-memory' | '24h', nullable
    - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `response_format` union
      - ResponseFormatText — Default response format. Used to generate text responses.
        - `type` 'text', required
      - ResponseFormatJSONSchema — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs).
        - `json_schema` JSONSchema, required — Structured Outputs configuration options, including a JSON Schema.
          - `name` string, required
          - `description` string
          - `schema` object
          - `strict` boolean, nullable
        - `type` 'json_schema', required
      - 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
    - `safety_identifier` string
    - `seed` integer, nullable
    - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority', nullable
    - `stop` union
      - string
      - string[]
    - `store` boolean, nullable
    - `stream_options` ChatCompletionStreamOptionsParam — Options for streaming response. Only set this when you set `stream: true`.
      - `include_obfuscation` boolean
      - `include_usage` boolean
    - `temperature` number, nullable
    - `tool_choice` union
      - 'none' | 'auto' | 'required'
      - ChatCompletionAllowedToolChoiceParam — Constrains the tools available to the model to a pre-defined set.
        - `allowed_tools` ChatCompletionAllowedToolsParam, required — Constrains the tools available to the model to a pre-defined set.
          - `mode` 'auto' | 'required', required
          - `tools` object[], required
        - `type` 'allowed_tools', required
      - ChatCompletionNamedToolChoiceParam — Specifies a tool the model should use. Use to force the model to call a specific function.
        - `function` OpenaiTypesChatChatCompletionNamedToolChoiceParamFunction, required
          - `name` string, required
        - `type` 'function', required
      - ChatCompletionNamedToolChoiceCustomParam — Specifies a tool the model should use. Use to force the model to call a specific custom tool.
        - `custom` OpenaiTypesChatChatCompletionNamedToolChoiceCustomParamCustom, required
          - `name` string, required
        - `type` 'custom', required
    - `tools` union[]
      - union
        - ChatCompletionFunctionToolParam — A function tool that can be used to generate a response.
          - `function` FunctionDefinition, required
            - `name` string, required
            - `description` string
            - `parameters` object
            - `strict` boolean, nullable
          - `type` 'function', required
        - ChatCompletionCustomToolParam — A custom tool that processes input using a specified format.
          - `custom` OpenaiTypesChatChatCompletionCustomToolParamCustom, required — Properties of the custom tool.
            - `name` string, required
            - `description` string
            - `format` union
              - …
          - `type` 'custom', required
    - `top_logprobs` integer, nullable
    - `top_p` number, nullable
    - `user` string
    - `verbosity` 'low' | 'medium' | 'high', nullable
    - `web_search_options` WebSearchOptions — This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
      - `search_context_size` 'low' | 'medium' | 'high'
      - `user_location` WebSearchOptionsUserLocation — Approximate location parameters for the search.
        - `approximate` WebSearchOptionsUserLocationApproximate, required — Approximate location parameters for the search.
          - `city` string
          - `country` string
          - `region` string
          - `timezone` string
        - `type` 'approximate', required
    - `stream` true, required
    - `tags` object, nullable
    - `parent_span_id` string, uuid, nullable

## Response `200`

Successful Response

- ChatCompletion — Represents a chat completion response returned by model, based on the provided input.
  - `id` string, required
  - `choices` Choice[], required
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call', required
    - `index` integer, required
    - `logprobs` ChoiceLogprobs — Log probability information for the choice.
      - `content` ChatCompletionTokenLogprob[], nullable
        - `token` string, required
        - `bytes` integer[], nullable
        - `logprob` number, required
        - `top_logprobs` TopLogprob[], required
          - `token` string, required
          - `bytes` integer[], nullable
          - `logprob` number, required
      - `refusal` ChatCompletionTokenLogprob[], nullable
        - `token` string, required
        - `bytes` integer[], nullable
        - `logprob` number, required
        - `top_logprobs` TopLogprob[], required
          - `token` string, required
          - `bytes` integer[], nullable
          - `logprob` number, required
    - `message` ChatCompletionMessage, required — A chat completion message generated by the model.
      - `content` string, nullable
      - `refusal` string, nullable
      - `role` 'assistant', required
      - `annotations` Annotation[], nullable
        - `type` 'url_citation', required
        - `url_citation` AnnotationURLCitation, required — A URL citation when using web search.
          - `end_index` integer, required
          - `start_index` integer, required
          - `title` string, required
          - `url` string, required
      - `audio` ChatCompletionAudio — If the audio output modality is requested, this object contains data about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).
        - `id` string, required
        - `data` string, required
        - `expires_at` integer, required
        - `transcript` string, required
      - `function_call` FunctionCallOutput — Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.
        - `arguments` string, required
        - `name` string, required
      - `tool_calls` union[], nullable
        - union
          - ChatCompletionMessageFunctionToolCall — A call to a function tool created by the model.
            - `id` string, required
            - `function` FunctionOutput, required — The function that the model called.
              - …
            - `type` 'function', required
          - ChatCompletionMessageCustomToolCall — A call to a custom tool created by the model.
            - `id` string, required
            - `custom` CustomOutput, required — The custom tool that the model called.
              - …
            - `type` 'custom', required
  - `created` integer, required
  - `model` string, required
  - `object` 'chat.completion', required
  - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority', nullable
  - `system_fingerprint` string, nullable
  - `usage` CompletionUsage — Usage statistics for the completion request.
    - `completion_tokens` integer, required
    - `prompt_tokens` integer, required
    - `total_tokens` integer, required
    - `completion_tokens_details` CompletionTokensDetails — Breakdown of tokens used in a completion.
      - `accepted_prediction_tokens` integer, nullable
      - `audio_tokens` integer, nullable
      - `reasoning_tokens` integer, nullable
      - `rejected_prediction_tokens` integer, nullable
    - `prompt_tokens_details` PromptTokensDetails — Breakdown of tokens used in the prompt.
      - `audio_tokens` integer, nullable
      - `cached_tokens` integer, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required (out of credits)
- `404` — Not Found
- `422` — Request Validation Error

---

[API](https://skmtc.dev/opper/apis/opper-api-v2.md) · [All operations](https://skmtc.dev/opper/apis/opper-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opper/opper-api-v2/revisions/d3ccdaa15678/schema)