telnyx 7.25.0 → 7.27.0

package/src/resources/ai/assistants/index.ts

@@ -11,6 +11,7 @@ export {
   type AssistantsList,
   type AudioVisualizerConfig,
   type AuthenticationMethod,
+  type AvatarSettingsRequest,
   type BooleanOpExpression,
   type ComparisonExpression,
   type ConversationFlow,
@@ -47,6 +48,7 @@ export {
   type SpeakNodeReq,
   type StartSpeakingPlan,
   type TelephonySettings,
+  type TelnyxAvatarSettings,
   type ToolNode,
   type ToolNodeReq,
   type TranscriptionEndpointingPlan,

package/src/resources/ai/assistants/versions.ts

@@ -13,7 +13,10 @@ import { path } from '../../../internal/utils/path';
 export class Versions extends APIResource {
   /**
    * Retrieves all versions of a specific assistant with complete configuration and
-   * metadata
+   * metadata. An assistant keeps at most 10 versions, including the main version.
+   * When an update takes it past that limit, the oldest versions are permanently
+   * deleted. The main version and any version referenced by a traffic distribution
+   * rule are never deleted this way.
    *
    * @example
    * ```ts
@@ -130,6 +133,14 @@ export interface UpdateAssistant {
    */
   a2a_agents?: Array<AssistantsAPI.AssistantA2AAgent>;
 
+  /**
+   * **Beta:** Configuration for the Telnyx open-source avatar provider. Use a stock
+   * avatar or an organization-owned custom avatar returned by the Avatars API.
+   * Discover the available stock catalog with GET /v2/ai/avatars and
+   * filter[avatar_type]=stock; follow meta.total_pages to load every page.
+   */
+  avatar_settings?: AssistantsAPI.AvatarSettingsRequest | null;
+
   /**
    * Conversation flow as supplied by API clients (create / update).
    *
@@ -357,6 +368,14 @@ export interface VersionUpdateParams {
    */
   a2a_agents?: Array<AssistantsAPI.AssistantA2AAgent>;
 
+  /**
+   * Body param: **Beta:** Configuration for the Telnyx open-source avatar provider.
+   * Use a stock avatar or an organization-owned custom avatar returned by the
+   * Avatars API. Discover the available stock catalog with GET /v2/ai/avatars and
+   * filter[avatar_type]=stock; follow meta.total_pages to load every page.
+   */
+  avatar_settings?: AssistantsAPI.AvatarSettingsRequest | null;
+
   /**
    * Body param: Conversation flow as supplied by API clients (create / update).
    *

package/src/resources/ai/audio.ts

@@ -130,9 +130,18 @@ export namespace AudioTranscribeResponse {
      */
     text: string;
 
+    /**
+     * Zero-indexed audio channel of this segment. Returned by the `deepgram/*` models
+     * when `multichannel` is enabled via `model_config` and the file has more than one
+     * channel. Segments from all channels are merged in one list ordered by start
+     * time.
+     */
+    channel?: number;
+
     /**
      * Speaker indices heard in this segment. Returned by the `deepgram/*` models when
-     * `diarize` is enabled via `model_config`.
+     * `diarize` is enabled via `model_config`. With `multichannel`, speakers are
+     * numbered per channel from 0, so identify a speaker by (`channel`, speaker).
      */
     speakers?: Array<number>;
 
@@ -197,10 +206,14 @@ export interface AudioTranscribeParams {
 
   /**
    * Additional model-specific configuration parameters. Only allowed with the
-   * `deepgram/*` models. Can include Deepgram-specific options such as
-   * `smart_format`, `punctuate`, `diarize`, `utterance`, `numerals`, and `language`.
-   * If `language` is provided both as a top-level parameter and in `model_config`,
-   * the top-level parameter takes precedence.
+   * `deepgram/*` models. Sent as a JSON string in multipart requests and passed
+   * through to Deepgram as query parameters. Any other model with `model_config`
+   * returns 422. Can include Deepgram-specific options such as `smart_format`,
+   * `punctuate`, `diarize` (speaker labels), `multichannel` (transcribe each channel
+   * independently; billed duration is file duration multiplied by the number of
+   * channels), `utterances`, `numerals`, and `language`. If `language` is provided
+   * both as a top-level parameter and in `model_config`, the top-level parameter
+   * takes precedence.
    */
   model_config?: { [key: string]: unknown };
 

package/src/resources/ai/avatars.ts

@@ -0,0 +1,252 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Create and manage real-time AI avatars
+ */
+export class Avatars extends APIResource {
+  /**
+   * Returns a paginated list of the Telnyx stock avatars and custom avatars
+   * available to the authenticated organization. Custom avatars owned by other
+   * organizations are never returned. The `image_url` value is suitable for
+   * displaying a thumbnail and may be refreshed by listing or retrieving the avatar
+   * again. `suggested_voice_id` recommends a compatible Telnyx voice for stock
+   * avatars and is an empty string for custom avatars; it does not change an AI
+   * Assistant's voice automatically.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const avatar of client.ai.avatars.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: AvatarListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AvatarsDefaultFlatPagination, Avatar> {
+    return this._client.getAPIList('/ai/avatars', DefaultFlatPagination<Avatar>, { query, ...options });
+  }
+
+  /**
+   * Uploads an image, validates its file type, size, safe decoding, and resolution,
+   * stores it in Telnyx-managed private storage, and creates an avatar owned by the
+   * authenticated organization. Creating an avatar does not update an AI Assistant;
+   * use the returned ID separately wherever the avatar is consumed. The avatar image
+   * is stored independently from the rendering model and background, which are
+   * selected where the avatar is consumed. Supported image types are JPEG, PNG, and
+   * WebP. Images may be up to 10 MiB, must be between 256 and 8192 pixels on each
+   * side, and may contain at most 40 megapixels. Each organization may have up to 20
+   * custom avatars. For best results, use a 16:9 landscape image, preferably 1920 by
+   * 1080 pixels and at least 1280 by 720 pixels. Show one centered, front-facing
+   * person from the shoulders up, keep the full head and hair visible with space
+   * around it, and use a sharp, evenly lit image with unobstructed eyes and mouth.
+   * Use a transparent PNG or WebP when the avatar will be combined with a selectable
+   * background. These composition recommendations are not enforced in the first
+   * release; the first release does not validate the number of faces, pose, or image
+   * content.
+   *
+   * @example
+   * ```ts
+   * const avatarResponse = await client.ai.avatars.create({
+   *   image_file: fs.createReadStream('path/to/file'),
+   *   name: 'Customer portrait',
+   * });
+   * ```
+   */
+  create(body: AvatarCreateParams, options?: RequestOptions): APIPromise<AvatarResponse> {
+    return this._client.post('/ai/avatars', multipartFormRequestOptions({ body, ...options }, this._client));
+  }
+
+  /**
+   * Returns a Telnyx stock avatar or a custom avatar owned by the authenticated
+   * organization. A custom avatar belonging to another organization is returned as
+   * not found.
+   *
+   * @example
+   * ```ts
+   * const avatarResponse = await client.ai.avatars.retrieve(
+   *   'avatar_0123456789abcdef0123456789abcdef',
+   * );
+   * ```
+   */
+  retrieve(avatarID: AvatarID, options?: RequestOptions): APIPromise<AvatarResponse> {
+    return this._client.get(path`/ai/avatars/${avatarID}`, options);
+  }
+
+  /**
+   * Updates the customer-facing name of a custom avatar owned by the authenticated
+   * organization. Stock avatars cannot be modified. To replace the image, create a
+   * new custom avatar so existing references keep their original content.
+   *
+   * @example
+   * ```ts
+   * const avatarResponse = await client.ai.avatars.update(
+   *   'avatar_0123456789abcdef0123456789abcdef',
+   *   { name: 'Updated portrait' },
+   * );
+   * ```
+   */
+  update(avatarID: AvatarID, body: AvatarUpdateParams, options?: RequestOptions): APIPromise<AvatarResponse> {
+    return this._client.patch(path`/ai/avatars/${avatarID}`, { body, ...options });
+  }
+}
+
+export type AvatarsDefaultFlatPagination = DefaultFlatPagination<Avatar>;
+
+export interface Avatar {
+  /**
+   * Stable identifier returned by the Avatars API. Discover available stock IDs with
+   * GET /v2/ai/avatars and filter[avatar_type]=stock rather than maintaining a fixed
+   * list. Custom avatar IDs use the `avatar_` prefix and must belong to the
+   * authenticated organization. The service validates that the selected avatar is
+   * available.
+   */
+  id: AvatarID;
+
+  /**
+   * Whether the avatar is provided by Telnyx or was uploaded by the authenticated
+   * organization.
+   */
+  avatar_type: AvatarType;
+
+  /**
+   * Indicates that avatar rendering runs on Telnyx-operated infrastructure.
+   */
+  hosted: true;
+
+  /**
+   * HTTPS image URL suitable for an avatar selection thumbnail. If the URL expires,
+   * list or retrieve the avatar again to refresh it.
+   */
+  image_url: string;
+
+  /**
+   * Customer-facing avatar name.
+   */
+  name: string;
+
+  /**
+   * Avatar provider. The first release supports Telnyx avatars.
+   */
+  provider: 'telnyx';
+
+  /**
+   * MIME type of a custom avatar image.
+   */
+  content_type?: 'image/jpeg' | 'image/png' | 'image/webp';
+
+  /**
+   * Time when the custom avatar was created.
+   */
+  created_at?: string;
+
+  /**
+   * Decoded height of a custom avatar image.
+   */
+  height_px?: number;
+
+  /**
+   * Expiration time of `image_url`. Omitted when the URL does not expire.
+   */
+  image_url_expires_at?: string;
+
+  /**
+   * Size of a custom avatar image in bytes.
+   */
+  size_bytes?: number;
+
+  /**
+   * Optional recommended Telnyx text-to-speech voice for this avatar. An omitted
+   * field or empty string means no recommendation is available. Custom avatars have
+   * no suggested voice. It is informational and selecting the avatar does not
+   * automatically change the AI Assistant's configured voice.
+   */
+  suggested_voice_id?: string;
+
+  /**
+   * Time when the custom avatar was last updated.
+   */
+  updated_at?: string;
+
+  /**
+   * Decoded width of a custom avatar image.
+   */
+  width_px?: number;
+}
+
+/**
+ * Stable identifier returned by the Avatars API. Discover available stock IDs with
+ * GET /v2/ai/avatars and filter[avatar_type]=stock rather than maintaining a fixed
+ * list. Custom avatar IDs use the `avatar_` prefix and must belong to the
+ * authenticated organization. The service validates that the selected avatar is
+ * available.
+ */
+export type AvatarID = string;
+
+export interface AvatarResponse {
+  data: Avatar;
+}
+
+/**
+ * Whether the avatar is provided by Telnyx or was uploaded by the authenticated
+ * organization.
+ */
+export type AvatarType = 'stock' | 'custom';
+
+export interface AvatarListParams extends DefaultFlatPaginationParams {
+  /**
+   * Return only stock or custom avatars.
+   */
+  'filter[avatar_type]'?: AvatarType;
+
+  /**
+   * Return the avatar with this exact ID.
+   */
+  'filter[id]'?: AvatarID;
+
+  /**
+   * Return avatars whose names contain this value, using case-insensitive matching.
+   */
+  'filter[name]'?: string;
+}
+
+export interface AvatarCreateParams {
+  /**
+   * JPEG, PNG, or WebP image file. The maximum file size is 10 MiB.
+   */
+  image_file: Uploadable;
+
+  /**
+   * Customer-facing name of the custom avatar.
+   */
+  name: string;
+}
+
+export interface AvatarUpdateParams {
+  /**
+   * New customer-facing name of the custom avatar.
+   */
+  name: string;
+}
+
+export declare namespace Avatars {
+  export {
+    type Avatar as Avatar,
+    type AvatarID as AvatarID,
+    type AvatarResponse as AvatarResponse,
+    type AvatarType as AvatarType,
+    type AvatarsDefaultFlatPagination as AvatarsDefaultFlatPagination,
+    type AvatarListParams as AvatarListParams,
+    type AvatarCreateParams as AvatarCreateParams,
+    type AvatarUpdateParams as AvatarUpdateParams,
+  };
+}

package/src/resources/ai/chat.ts

@@ -72,12 +72,26 @@ export interface ChatCompletionRequest {
   logprobs?: boolean;
 
   /**
-   * 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.
+   * Maximum number of completion (output) tokens, including reasoning and answer
+   * tokens combined. An omitted or null limit defaults to 8192 unless the model is
+   * excluded from that default; excluded models leave the limit to the serving
+   * engine. Explicit values and applied defaults are clamped to the model's
+   * max_completion_tokens metadata when that ceiling is set (see GET
+   * /v2/ai/openai/models). An omitted limit on an excluded model remains unset even
+   * when metadata declares a ceiling. Input and output together must fit the model's
+   * context window. Set an explicit limit when a bounded generation budget is
+   * required. For current Telnyx-hosted models, omitted or null limits default to
+   * 8192 for `zai-org/GLM-5.3`, `zai-org/GLM-5.3-Flash` and
+   * `deepseek-ai/DeepSeek-V4.1-Flash`. The hosted exclusions are
+   * `moonshotai/Kimi-K3`, `moonshotai/Kimi-K2.6`, `moonshotai/Kimi-K2.5`,
+   * `zai-org/GLM-5.2`, `zai-org/GLM-5.1-FP8`, `MiniMaxAI/MiniMax-M3-MXFP8`,
+   * `MiniMaxAI/MiniMax-M2.7`, `Qwen/Qwen3.8-27B`, `Qwen/Qwen3-235B-A22B`,
+   * `deepseek-ai/DeepSeek-V4-Flash-0731`, `meta-llama/Llama-3.3-70B-Instruct`,
+   * `meta-llama/Meta-Llama-3.1-70B-Instruct`,
+   * `meta-llama/Meta-Llama-3.1-8B-Instruct` and `google/gemma-2b-it`. Legacy
+   * external and fine-tuned model IDs can also bypass the default; model discovery
+   * reports completion ceilings, not whether this default applies. Set an explicit
+   * limit for predictable behavior across models.
    */
   max_tokens?: number | null;
 

package/src/resources/ai/conversations/conversations.ts

@@ -304,6 +304,15 @@ export interface ConversationListParams {
    */
   'metadata->assistant_id'?: string;
 
+  /**
+   * Filter by assistant version ID (e.g.,
+   * `metadata->assistant_version_id=eq.20250812T114318034399`). The version that
+   * handled the conversation is stored in metadata when the conversation starts;
+   * conversations created before this field was tracked, or that never resolved a
+   * version, have no `assistant_version_id` and do not match this filter.
+   */
+  'metadata->assistant_version_id'?: string;
+
   /**
    * Filter by call control ID (e.g., `metadata->call_control_id=eq.v3:123`)
    */

package/src/resources/ai/index.ts

@@ -22,6 +22,7 @@ export {
   type AssistantsList,
   type AudioVisualizerConfig,
   type AuthenticationMethod,
+  type AvatarSettingsRequest,
   type BooleanOpExpression,
   type ComparisonExpression,
   type ConversationFlow,
@@ -58,6 +59,7 @@ export {
   type SpeakNodeReq,
   type StartSpeakingPlan,
   type TelephonySettings,
+  type TelnyxAvatarSettings,
   type ToolNode,
   type ToolNodeReq,
   type TranscriptionEndpointingPlan,
@@ -89,6 +91,17 @@ export {
   type AudioTranscribeResponse,
   type AudioTranscribeParams,
 } from './audio';
+export {
+  Avatars,
+  type Avatar,
+  type AvatarID,
+  type AvatarResponse,
+  type AvatarType,
+  type AvatarListParams,
+  type AvatarCreateParams,
+  type AvatarUpdateParams,
+  type AvatarsDefaultFlatPagination,
+} from './avatars';
 export { Chat, type BucketIDs, type ChatCompletionRequest } from './chat';
 export {
   Clusters,
@@ -166,6 +179,7 @@ export {
   type PayToolParams,
   type SharedToolResponse,
   type UpdateDynamicVariablesToolParams,
+  type VisionToolParams,
   type ToolListParams,
   type ToolCreateParams,
   type ToolUpdateParams,

package/src/resources/ai/memory/namespaces/index.ts

@@ -15,6 +15,7 @@ export {
   type ProfileListResponse,
   type ProfileDeleteResponse,
   type ProfileIngestResponse,
+  type ProfilePreviewResponse,
   type ProfileRecallResponse,
   type ProfileRememberResponse,
   type ProfileRetrieveSummaryResponse,
@@ -24,6 +25,7 @@ export {
   type ProfileRecallParams,
   type ProfileRememberParams,
   type ProfileRetrieveSummaryParams,
+  type ProfilePreviewParams,
   type ProfileListResponsesDefaultFlatPagination,
 } from './profiles/index';
 export { Settings, type NamespaceSettingsResponse, type SettingPatchAllParams } from './settings';

package/src/resources/ai/memory/namespaces/namespaces.ts

@@ -13,6 +13,8 @@ import {
   ProfileListParams,
   ProfileListResponse,
   ProfileListResponsesDefaultFlatPagination,
+  ProfilePreviewParams,
+  ProfilePreviewResponse,
   ProfileRecallParams,
   ProfileRecallResponse,
   ProfileRememberParams,
@@ -174,6 +176,7 @@ export declare namespace Namespaces {
     type ProfileListResponse as ProfileListResponse,
     type ProfileDeleteResponse as ProfileDeleteResponse,
     type ProfileIngestResponse as ProfileIngestResponse,
+    type ProfilePreviewResponse as ProfilePreviewResponse,
     type ProfileRecallResponse as ProfileRecallResponse,
     type ProfileRememberResponse as ProfileRememberResponse,
     type ProfileRetrieveSummaryResponse as ProfileRetrieveSummaryResponse,
@@ -184,6 +187,7 @@ export declare namespace Namespaces {
     type ProfileRecallParams as ProfileRecallParams,
     type ProfileRememberParams as ProfileRememberParams,
     type ProfileRetrieveSummaryParams as ProfileRetrieveSummaryParams,
+    type ProfilePreviewParams as ProfilePreviewParams,
   };
 
   export {

package/src/resources/ai/memory/namespaces/profiles/index.ts

@@ -14,6 +14,7 @@ export {
   type ProfileListResponse,
   type ProfileDeleteResponse,
   type ProfileIngestResponse,
+  type ProfilePreviewResponse,
   type ProfileRecallResponse,
   type ProfileRememberResponse,
   type ProfileRetrieveSummaryResponse,
@@ -23,6 +24,7 @@ export {
   type ProfileRecallParams,
   type ProfileRememberParams,
   type ProfileRetrieveSummaryParams,
+  type ProfilePreviewParams,
   type ProfileListResponsesDefaultFlatPagination,
 } from './profiles';
 export {

package/src/resources/ai/memory/namespaces/profiles/profiles.ts

@@ -203,6 +203,42 @@ export class Profiles extends APIResource {
     const { namespace } = params;
     return this._client.get(path`/ai/memory/namespaces/${namespace}/profiles/${profileID}/summary`, options);
   }
+
+  /**
+   * Try a candidate note on one profile and see how that profile's summary would
+   * read under it, without saving the note and without touching the stored summary.
+   * Composes the same source query the apply path
+   * (`PATCH /ai/memory/namespaces/{namespace}/settings`) would use, so a preview
+   * cannot drift from what saving the note would produce. Reads the candidate alone
+   * -- the namespace's current instructions and the profile's stored summary are
+   * neither read nor replaced. Bounded at 120 seconds: the summary is generated on
+   * the spot rather than read from a stored one. Nothing about the request is
+   * stored.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.ai.memory.namespaces.profiles.preview(
+   *     'profile_id',
+   *     {
+   *       namespace: 'namespace',
+   *       instructions:
+   *         'Lead with billing status. Prefer plain language over jargon.',
+   *     },
+   *   );
+   * ```
+   */
+  preview(
+    profileID: string,
+    params: ProfilePreviewParams,
+    options?: RequestOptions,
+  ): APIPromise<ProfilePreviewResponse> {
+    const { namespace, ...body } = params;
+    return this._client.post(path`/ai/memory/namespaces/${namespace}/profiles/${profileID}/summary/preview`, {
+      body,
+      ...options,
+    });
+  }
 }
 
 export type ProfileListResponsesDefaultFlatPagination = DefaultFlatPagination<ProfileListResponse>;
@@ -287,6 +323,23 @@ export namespace ProfileIngestResponse {
   }
 }
 
+export interface ProfilePreviewResponse {
+  data: ProfilePreviewResponse.Data;
+}
+
+export namespace ProfilePreviewResponse {
+  export interface Data {
+    profile_id: string;
+
+    /**
+     * The summary this profile would carry under the candidate note. Null when nothing
+     * was generated -- the same signal `GET /summary` uses for a profile with no card
+     * yet.
+     */
+    text: string | null;
+  }
+}
+
 export interface ProfileRecallResponse {
   data: Array<ProfileRecallResponse.Data>;
 }
@@ -441,6 +494,22 @@ export interface ProfileRetrieveSummaryParams {
   namespace: string;
 }
 
+export interface ProfilePreviewParams {
+  /**
+   * Path param: The namespace. `default` exists for every organization.
+   */
+  namespace: string;
+
+  /**
+   * Body param: The candidate note to try. `null`, empty, or whitespace-only
+   * previews the neutral default -- the summary a profile returns to when
+   * instructions are cleared. Capped at 2000 characters, the same cap
+   * `PATCH /settings` applies on save; a longer note is refused with `422` before
+   * anything is generated.
+   */
+  instructions?: string | null;
+}
+
 Profiles.Memories = Memories;
 Profiles.Sources = Sources;
 
@@ -450,6 +519,7 @@ export declare namespace Profiles {
     type ProfileListResponse as ProfileListResponse,
     type ProfileDeleteResponse as ProfileDeleteResponse,
     type ProfileIngestResponse as ProfileIngestResponse,
+    type ProfilePreviewResponse as ProfilePreviewResponse,
     type ProfileRecallResponse as ProfileRecallResponse,
     type ProfileRememberResponse as ProfileRememberResponse,
     type ProfileRetrieveSummaryResponse as ProfileRetrieveSummaryResponse,
@@ -460,6 +530,7 @@ export declare namespace Profiles {
     type ProfileRecallParams as ProfileRecallParams,
     type ProfileRememberParams as ProfileRememberParams,
     type ProfileRetrieveSummaryParams as ProfileRetrieveSummaryParams,
+    type ProfilePreviewParams as ProfilePreviewParams,
   };
 
   export {

package/src/resources/ai/openai/chat.ts

@@ -97,12 +97,26 @@ export interface ChatCreateCompletionParams {
   logprobs?: boolean;
 
   /**
-   * 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.
+   * Maximum number of completion (output) tokens, including reasoning and answer
+   * tokens combined. An omitted or null limit defaults to 8192 unless the model is
+   * excluded from that default; excluded models leave the limit to the serving
+   * engine. Explicit values and applied defaults are clamped to the model's
+   * max_completion_tokens metadata when that ceiling is set (see GET
+   * /v2/ai/openai/models). An omitted limit on an excluded model remains unset even
+   * when metadata declares a ceiling. Input and output together must fit the model's
+   * context window. Set an explicit limit when a bounded generation budget is
+   * required. For current Telnyx-hosted models, omitted or null limits default to
+   * 8192 for `zai-org/GLM-5.3`, `zai-org/GLM-5.3-Flash` and
+   * `deepseek-ai/DeepSeek-V4.1-Flash`. The hosted exclusions are
+   * `moonshotai/Kimi-K3`, `moonshotai/Kimi-K2.6`, `moonshotai/Kimi-K2.5`,
+   * `zai-org/GLM-5.2`, `zai-org/GLM-5.1-FP8`, `MiniMaxAI/MiniMax-M3-MXFP8`,
+   * `MiniMaxAI/MiniMax-M2.7`, `Qwen/Qwen3.8-27B`, `Qwen/Qwen3-235B-A22B`,
+   * `deepseek-ai/DeepSeek-V4-Flash-0731`, `meta-llama/Llama-3.3-70B-Instruct`,
+   * `meta-llama/Meta-Llama-3.1-70B-Instruct`,
+   * `meta-llama/Meta-Llama-3.1-8B-Instruct` and `google/gemma-2b-it`. Legacy
+   * external and fine-tuned model IDs can also bypass the default; model discovery
+   * reports completion ceilings, not whether this default applies. Set an explicit
+   * limit for predictable behavior across models.
    */
   max_tokens?: number | null;