---
title: "Create a chat completion"
method: POST
path: "/ai/chat/completions"
tags: ["Chat"]
deprecated: true
---

# Create a chat completion

`POST /ai/chat/completions`

> **Deprecated.**

**Deprecated**: Use `POST /v2/ai/openai/chat/completions` instead. Chat with a language model. This endpoint is consistent with the [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat) and may be used with the OpenAI JS or Python SDK.

## Request body

- ChatCompletionRequest
  - `messages` ChatCompletionSystemMessageParam[], required — A list of the previous chat messages for context.
    - `content` union, required
      - string
      - object[]
        - `type` 'text' | 'image_url', required
        - `text` string
        - `image_url` string
    - `role` 'system' | 'user' | 'assistant' | 'tool', required
  - `model` string — The language model to chat with.
  - `service_tier` string — The service tier to use for this request. Supported values vary by model; use `GET /v2/ai/openai/models` and inspect the model's `service_tiers` field. If omitted, Telnyx-hosted models use `default`.
  - `region` 'USA' | 'EU' | 'AUS' | 'UAE' — Optional data-residency region the request should be served from, using the same vocabulary as your account's Data Locality setting. Behavior depends on `mode`. Supported for Telnyx-hosted models only: a request routed to an external provider never passes through Telnyx model routing, so a region cannot be enforced for it. Omit for today's latency-based routing.
  - `mode` 'preferred' | 'strict' — How strictly `region` is applied. `preferred` (the default when `region` is set) tries that region first and falls back to another when the model cannot be served there, so a request that would have succeeded still succeeds. `strict` pins the request: it is served from that region or it fails with a 422, never redirected to another region. Requires `region`.
  - `api_key_ref` string — If you are using an external inference provider like xAI or OpenAI, this field allows you to pass along a reference to your API key. After creating an [integration secret](https://developers.telnyx.com/api-reference/integration-secrets/create-a-secret) for you API key, pass the secret's `identifier` in this field.
  - `stream` boolean — Whether or not to stream data-only server-sent events as they become available.
  - `temperature` number — Adjusts the "creativity" of the model. Lower values make the model more deterministic and repetitive, while higher values make the model more random and creative.
  - `max_tokens` integer, nullable — Maximum number of completion (output) tokens the model may generate per request. Defaults to 8192 when omitted or `null`. Set a higher value to allow longer completions. The model's `max_completion_tokens` metadata (see `GET /ai/models`), when set, caps both the default and any larger explicit value. Reasoning models consume this budget across reasoning and answer tokens combined.
  - `tools` union[] — The `function` tool type follows the same schema as the [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat). The `retrieval` tool type is unique to Telnyx. You may pass a list of [embedded storage buckets](https://developers.telnyx.com/api-reference/embeddings/embed-documents) for retrieval-augmented generation.
    - union
      - ChatCompletionToolParam
        - `type` 'function', required
        - `function` FunctionDefinition, required
          - `name` string, required
          - `description` string
          - `parameters` object
      - Retrieval
        - `type` 'retrieval', required
        - `retrieval` BucketIds, required
          - `bucket_ids` string[], required — List of [embedded storage buckets](https://developers.telnyx.com/api-reference/embeddings/embed-documents) to use for retrieval-augmented generation.
          - `max_num_results` integer — The maximum number of results to retrieve as context for the language model.
  - `tool_choice` 'none' | 'auto' | 'required'
  - `response_format` union — Output format for the model response. `text` returns plain text, `json_object` enables JSON mode (valid JSON output without a schema), and `json_schema` constrains the output to a schema you supply. For guaranteed schema-conformant structured output on Telnyx-hosted models, use `json_schema`.
    - ResponseFormatText — Plain text output.
      - `type` 'text', required
    - ResponseFormatJsonObject — JSON mode: the model output is valid JSON, without a schema.
      - `type` 'json_object', required
    - ResponseFormatJsonSchemaParam — Structured output: the model output is constrained to the JSON schema supplied in `json_schema`.
      - `type` 'json_schema', required
      - `json_schema` ResponseFormatJsonSchema, required — The JSON schema configuration, required when `type` is `json_schema`. Matches the [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs) `json_schema` response format.
        - `name` string, required — The name of the response format. Used for clarity only.
        - `description` string — A description of what the response format is for, typically used to guide the model.
        - `schema` object — The JSON schema the model output must conform to. A valid [JSON Schema](https://json-schema.org) object, e.g. a Pydantic `model_json_schema()` export.
        - `strict` boolean — Enables strict schema adherence when supported by the model. If the generated output does not match the provided schema, the request fails instead of returning non-conformant output.
  - `min_p` number — This is an alternative to `top_p` that [many prefer](https://github.com/huggingface/transformers/issues/27670). Must be in [0, 1].
  - `n` number — This will return multiple choices for you instead of a single chat completion.
  - `use_beam_search` boolean — Setting this to `true` will allow the model to [explore more completion options](https://huggingface.co/blog/how-to-generate#beam-search). This is not supported by OpenAI.
  - `best_of` integer — This is used with `use_beam_search` to determine how many candidate beams to explore.
  - `length_penalty` number — This is used with `use_beam_search` to prefer shorter or longer completions.
  - `early_stopping` boolean — This is used with `use_beam_search`. If `true`, generation stops as soon as there are `best_of` complete candidates; if `false`, a heuristic is applied and the generation stops when is it very unlikely to find better candidates.
  - `logprobs` boolean — Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`.
  - `top_logprobs` integer — This is used with `logprobs`. An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.
  - `frequency_penalty` number — Higher values will penalize the model from repeating the same output tokens.
  - `presence_penalty` number — Higher values will penalize the model from repeating the same output tokens.
  - `top_p` number — An alternative or complement to `temperature`. This adjusts how many of the top possibilities to consider.
  - `stop` union — Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
    - string
    - string[]
  - `seed` integer — If specified, the system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.
  - `enable_thinking` boolean — Whether to enable the thinking/reasoning phase for models that support it (e.g., QwQ, Qwen3). When set to false, the model will skip the internal reasoning step and respond directly, which can reduce latency. Defaults to true.
  - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' — Controls the reasoning effort for models that support it. When set, the model spends more or less compute on internal reasoning before generating its response. Supported values: none, minimal, low, medium, high, xhigh, max. Not all models support all values; unsupported values are rejected with a 400 error. When omitted, reasoning models use their default effort level.

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

## Changes

> 99 revisions in range; 1 not diffed.

- **2026-09-26** `74024ca53801` — 2 info
  - the request property `max_tokens` became nullable
  - the `max_tokens` request property default value `8192` was added
- **2026-09-16** `a6a61a29ecdd` — 1 breaking, 4 warning, 4 info
  - the `response_format` request property type changed from `object` to no type
  - removed the request property `guided_choice`
  - removed the request property `guided_json`
  - removed the request property `guided_regex`
  - …5 more
- **2026-07-29** `f8c0ade27450` — 1 info
  - added the new optional request property `service_tier`

[Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/chat/completions/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/227c33b1ac9c?raw)