Create a chat completion

POST

/ai/chat/completions

Chat

Chat with a language model. This endpoint is consistent with the OpenAI Chat Completions API and may be used with the OpenAI JS or Python SDK.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/ai/chat/completions' \
--header 'Content-Type: application/json' \
--data-raw '{
    "messages": [
        {
            "content": "You are a friendly chatbot.",
            "role": "system"
        },
        {
            "content": "Hello, world!",
            "role": "user"
        }
    ]
}'

Response Example

200 - Example 1

null

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

api_key_ref

string

optional

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 for you API key, pass the secret's identifier in this field.

best_of

integer

optional

This is used with use_beam_search to determine how many candidate beams to explore.

early_stopping

boolean

optional

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.

Default:

false

frequency_penalty

number

optional

Higher values will penalize the model from repeating the same output tokens.

Default:

guided_choice

array[string]

optional

If specified, the output will be exactly one of the choices.

guided_json

object

optional

Must be a valid JSON schema. If specified, the output will follow the JSON schema.

guided_regex

string

optional

If specified, the output will follow the regex pattern.

length_penalty

number

optional

This is used with use_beam_search to prefer shorter or longer completions.

Default:

logprobs

boolean

optional

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.

Default:

false

max_tokens

integer

optional

Maximum number of completion tokens the model should generate.

messages

array[object (ChatCompletionSystemMessageParam) {2}]

required

A list of the previous chat messages for context.

Example:

[{"content":"You are a friendly chatbot.","role":"system"},{"content":"Hello, world!","role":"user"}]

content

required

role

enum<string>

required

Allowed values:

systemuserassistanttool

min_p

number

optional

This is an alternative to top_p that many prefer. Must be in [0, 1].

model

string

optional

The language model to chat with. If you are optimizing for speed + price, try meta-llama/Meta-Llama-3.1-8B-Instruct. For quality, try meta-llama/Meta-Llama-3.1-70B-Instruct. Or explore our LLM Library.

Default:

meta-llama/Meta-Llama-3.1-8B-Instruct

number

optional

This will return multiple choices for you instead of a single chat completion.

presence_penalty

number

optional

Higher values will penalize the model from repeating the same output tokens.

Default:

response_format

object (ChatCompletionResponseFormatParam)

optional

Use this is you want to guarantee a JSON output without defining a schema. For control over the schema, use guided_json.

type

enum<string>

required

Allowed values:

textjson_object

stream

boolean

optional

Whether or not to stream data-only server-sent events as they become available.

Default:

false

temperature

number

optional

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.

Default:

0.1

tool_choice

enum<string>

optional

Allowed values:

noneautorequired

tools

array [oneOf]

optional

The function tool type follows the same schema as the OpenAI Chat Completions API. The retrieval tool type is unique to Telnyx. You may pass a list of embedded storage buckets for retrieval-augmented generation.

object (Function)

optional

object (Retrieval)

optional

top_logprobs

integer

optional

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.

top_p

number

optional

An alternative or complement to temperature. This adjusts how many of the top possibilities to consider.

use_beam_search

boolean

optional

Setting this to true will allow the model to explore more completion options. This is not supported by OpenAI.

Default:

false

Examples

Responses

🟢200OK

application/json

Successful Response

Body

No schema defined

🟠422Parameter Error

Modified at 2025-06-16 19:14:41

Transcribe speech to text

Get available models