Skip to main content
The inference plane serves three endpoints. All of them authenticate with an AI Gateway token key (ltg_sk_...) issued through the management API. Telnyx account API keys, provider secrets and any other credential are rejected on this plane. Compatibility is bounded by the AI Gateway contract, not by every option the OpenAI and Anthropic SDKs expose; see Supported request fields and Supported Messages fields.

Models

These Telnyx-hosted models are billed to your Telnyx account. Use these model names in the model field:
  • Kimi-K3
  • Kimi-K2.6
  • Kimi-K2.5
  • GLM-5.3
  • GLM-5.3-Flash
  • GLM-5.2
  • GLM-5.1-FP8
  • MiniMax-M3-MXFP8
  • MiniMax-M2.7
  • Qwen3.8-27B
  • Qwen3-235B-A22B
  • DeepSeek-V4.1-Flash
  • DeepSeek-V4-Flash-0731
  • Llama-3.3-70B-Instruct
  • Meta-Llama-3.1-70B-Instruct
  • Meta-Llama-3.1-8B-Instruct
  • gemma-2b-it
A group lists the model names its keys may call in allowed_models; a key can narrow that list further. Per-request output and prompt limits are listed under Request size limits.

Bring-your-own-key models

These models run on your own provider account with a provider key and are billed by that provider. Add them to allowed_models like any other model. A BYOK model works only when the calling key’s group has an attached provider key for that model’s provider. Without one, requests fail with 503 and code enforcement_unavailable; they never fall back to a Telnyx-hosted model. Every BYOK model works on /v1/chat/completions. Anthropic BYOK models also work on /v1/messages.

Model discovery

GET /v1/models returns the models the supplied key may use: the intersection of the key’s allowed_models and its group’s list. It is not a global catalog, and it does not charge against any budget. Hosted model entries include capabilities: chat_tools, chat_tools_stream, chat_tool_choice, parallel_tool_calls, context_window, context_includes_output, context_enforcement, output_token_limit, default_output_tokens and max_request_body_bytes. Context windows include input and output. output_token_limit is the model’s explicit completion ceiling, or its total context bound when no separate ceiling exists. default_output_tokens: null means an omitted limit is left to the serving engine. reservation_accounting describes conservative budget/TPM accounting; it is not an exact tokenizer count. BYOK discovery entries retain their existing shape and may omit capabilities. A newly created key can return 503 while its policy is being provisioned. Check the optional x-ltg-enforcement-reason: provisioning header and follow the pending-provisioning guidance before sending inference requests.

OpenAI SDK

Point the OpenAI SDK at the inference base URL and use the token key as the API key.
The optional user field attributes the request to an application end user for budgeting and reporting. See End-user identity.

Streaming

Set stream: true and consume the stream to completion. A stream that starts with HTTP 200 can still fail later; handle SDK exceptions and close the stream.

Anthropic SDK

POST /v1/messages is available only for Anthropic models used with your own Anthropic key (Anthropic BYOK models). A request to /v1/messages with a Telnyx-hosted model or an OpenAI BYOK model returns 400 with code invalid_request; call those models on /v1/chat/completions. Anthropic BYOK models work on both endpoints.
The Anthropic SDK appends /v1/messages to its base URL, so set the base URL to the gateway root without the /v1 suffix. The SDK sends the token key in x-api-key, which the gateway accepts. Authorization: Bearer is also accepted; if both headers are present they must carry the same token.
Raw HTTP requests must send anthropic-version: 2023-06-01; the SDKs add it automatically. metadata.user_id and the OpenAI user field identify the same end-user namespace. The endpoint streams standard Anthropic server-sent events (message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop). An error after the stream has started arrives as an event: error frame.

Supported Messages fields

Content blocks of type text, tool_use and tool_result are supported. image blocks are rejected. OpenAI-specific fields (frequency_penalty, presence_penalty, n, seed, response_format, user, stream_options, parallel_tool_calls) are rejected on the Messages endpoint. Hosted Chat Completions tool calls are supported by the listed Kimi, GLM, MiniMax, Qwen and DeepSeek models, plus Llama-3.3-70B-Instruct. The two Meta Llama 3.1 models and gemma-2b-it reject tools before dispatch. Return the assistant’s tool_calls message and matching role: "tool" messages with tool_call_id to continue the conversation. Preserve assistant reasoning_content when returned; raw responses and OpenAI SDK message serialization are accepted for these hosted models. The application executes the function; the gateway only carries its definition, call and result.

Retries and timeouts

Inference is not idempotent. An SDK retry after a timeout or disconnect can dispatch a second billed request, and a timeout is not evidence that the first request did no provider work. The examples on this page set max_retries=0; if your application retries, do so deliberately and only for errors that occurred before dispatch (for example 401, 403 or 429 with Retry-After). See Errors. Token groups can configure gateway retries and fallbacks. These request headers can tighten the policy without changing the group: The other supported x-ltg-* request header is x-ltg-metadata for request tags. Client-supplied fallback headers and other routing controls remain rejected. The production request lifetime is 300 seconds, with each provider attempt bounded to 295 seconds. Ordinary streaming requests wait up to 30 seconds for the first provider event; large-prompt requests can wait up to the attempt limit. Subsequent stream reads have a 30-second idle timeout. Group and request policies can shorten the first-event wait. Client-side timeouts do not extend these limits.

Request size limits

Hosted models use their published total context windows. Input, tool definitions, conversation history and requested output must fit the model’s context. The actual serving tokenizer enforces this limit; discovery reports the active published values and request-body envelope. Hosted output limits follow the model-specific Telnyx Chat Completions policy. The output budget includes reasoning and answer tokens combined. An explicit limit above a declared completion ceiling is clamped to that ceiling. Without a separate ceiling, an output request larger than the total context is rejected. The total context is not an available output allowance after a prompt has consumed part of it. An omitted or null limit defaults to 8,192 for GLM-5.3, GLM-5.3-Flash and DeepSeek-V4.1-Flash. Other hosted models leave the limit to the serving engine. Use GET /v1/models to inspect the active limits and defaults for the calling key. BYOK retains its existing conservative prompt allowance (about 128k, or 96k for gpt-4o/gpt-4o-mini) and 16,384 output-token cap; the larger hosted windows do not expand BYOK limits. A known backend context rejection returns 400 context_length_exceeded: reduce input and/or requested output. It is terminal and does not trigger retry or fallback. The separate physical JSON-body limit reported by max_request_body_bytes includes escaping, tools and history; exceeding it returns 413 request_too_large. Published context is not a guarantee of capacity or successful completion at that size on every serving backend. Timeouts return 504 upstream_timeout, and other upstream failures can return 502 upstream_error. Set max_tokens (or max_completion_tokens) explicitly to bound generation and reservations. For hosted models that leave an omitted or null limit to the engine, the gateway reserves the full context window as output, even if an explicit request would have a separate completion ceiling. For example, Kimi-K3 reserves 1,000,000 output tokens when the limit is omitted. Models with an 8,192 default reserve that default; explicit limits reserve the resolved limit after clamping. Budget and TPM accounting also includes a conservative input bound from normalized JSON bytes plus 256 per message. These reservations are not actual token counts or charges. Omitted limits can exhaust budget/TPM headroom or reduce the number of concurrent requests that fit within a budget. Configured retries/fallbacks can add further reservations. See Reservations. Output-token admission does not guarantee delivery of that many tokens. Hosted buffered Chat responses can be up to 128 MiB, subject to available buffering capacity; responses above 1 MiB are not cached. BYOK buffered responses remain limited to 1 MiB. Hosted streams have a 1 MiB per-event limit without an aggregate response-size cap; BYOK retains its 8 MiB aggregate limit. Enabled response guardrails limit buffered evaluation to 1 MiB and stream retention to 8 MiB, including passthrough streaming; exceeding these limits fails the request. Server-side request lifetimes still apply; see Retries and timeouts.

Supported request fields

Unknown top-level fields and options rejected by gateway validation return 400. Model-specific validation may also happen upstream; upstream failures can return 502 upstream_error.

Chat Completions

Structured JSON on Telnyx-hosted models: All 17 models support json_schema without streaming. All except Meta-Llama-3.1-8B-Instruct support json_object. Both formats support stream: true where enabled, except on Llama-3.3-70B-Instruct. Unsupported combinations return 400 before inference.json_object does not enforce requested fields or values. Use json_schema when a specific structure is required. Schemas are limited to 16 KiB, 16 levels and 512 schema nodes; remote references are rejected. Handle truncation, refusals and stream errors, and validate the completed output.
Image parts must be inline data:image/...;base64,... URLs (PNG, JPEG, GIF or WebP). Remote image URLs are rejected.

Not supported

  • Custom provider URLs, provider credentials, routing or fallback controls in the request body.
  • Remote image URLs.
  • Unlisted beta headers and options.
  • The Responses API, embeddings, image and audio generation, batches and realtime APIs. These are not part of the AI Gateway surface; see the Telnyx Inference API for those capabilities.