---
title: "Create chat completion"
method: POST
path: "/v1/chat/completions"
---

# Create chat completion

`POST /v1/chat/completions`

Create a chat completion using various AI models. Compatible with the OpenAI Chat Completions format.

## Request body

- ChatCompletionRequest
  - `model` string — The model name. If omitted, defaults to openai/gpt-4o-mini.
  - `messages` Message[], required — An array of message objects with role and content
    - `role` 'user' | 'assistant' | 'system' | 'tool', required — The role of the message sender
    - `content` string, required — The content of the message
    - `name` string — The name of the tool (for tool messages)
  - `max_tokens` integer — Maximum number of tokens to generate
  - `temperature` number — Controls randomness of the output
  - `top_p` number — Controls diversity of the output
  - `stream` boolean — Enable Server-Sent Events (SSE) streaming responses
  - `tools` Tool[] — Available tools for the model. Supports `function` tools for custom function calling and `web_search` for real-time web search.
    - `type` 'function' | 'web_search', required — The type of tool. Use `function` for custom function calling, or `web_search` to enable the model to search the web for real-time information. When `type=web_search`, Requesty translates the tool to the provider's native web search format (Anthropic, Vertex/Gemini, OpenAI, xAI, Perplexity).
    - `function` Function
      - `name` string, required — The name of the function
      - `description` string, required — The description of the function
      - `parameters` object, required — The parameters schema for the function
  - `tool_choice` string — Specifies how tool calling should be handled
  - `response_format` object — For structured responses (some models only)

## Response `200`

Chat completion response

- ChatCompletionResponse
  - `id` string, required — Unique identifier for the completion
  - `object` string, required — Object type
  - `created` integer, required — Timestamp of creation
  - `model` string, required — Model used for completion
  - `usage` Usage
    - `completion_tokens` integer — Number of tokens in the generated completion.
    - `completion_tokens_details` CompletionTokenDetails
      - `reasoning_tokens` integer — Tokens generated for reasoning.
    - `prompt_tokens` integer — Number of tokens in the prompt.
    - `prompt_tokens_details` PromptTokenDetails
      - `cached_tokens` integer — Cached tokens present in the prompt.
      - `caching_tokens` integer — Tokens that were cached following this prompt.
    - `total_tokens` integer — Total number of tokens used (prompt + completion).
    - `cost` number, double — Requesty's USD cost for this request. Returned by default on non-streaming responses. For streaming, pass `stream_options: {"include_usage": true}` to receive a final chunk with `usage` (including `cost`).
  - `choices` Choice[], required
    - `index` integer
    - `message` Message
      - `role` 'user' | 'assistant' | 'system' | 'tool', required — The role of the message sender
      - `content` string, required — The content of the message
      - `name` string — The name of the tool (for tool messages)
    - `finish_reason` string

## Other responses

- `400` — Bad request - malformed payload or invalid parameters.
- `401` — Unauthorized - missing or empty Authorization header.
- `402` — Payment required - organization balance exhausted.
- `403` — Forbidden - invalid token or model not in access list.
- `404` — Not found - provider/model not supported.
- `429` — Rate limit exceeded. Retry after the Retry-After header value.
- `500` — Internal server error.
- `502` — Bad gateway - upstream provider returned an invalid response.

---

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