Telnyx Ai Inference - Java 是一个面向 Java 开发者的技能包，提供访问 Telnyx AI 接口所需的 SDK 示例与安装说明。
用途
该技能用于在 Java 应用中接入 Telnyx 的 AI 能力，涵盖语言模型推理、语音转文字、嵌入处理以及面向对话的 AI 洞察分析。它适合需要以 Java 调用 Telnyx AI 服务的开发场景，例如构建对话系统、对通话或音频内容做转写与摘要、对文档做嵌入，以及聚合会话洞察。
安装与初始化
依赖坐标：
Maven：
<dependency> <groupId>com.telnyx.sdk</groupId> <artifactId>telnyx</artifactId> <version>6.89.0</version> </dependency>
Gradle：
implementation("com.telnyx.sdk:telnyx:6.89.0")
初始化客户端：
import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
文档中的示例均假定 client 已按上述方式初始化。
主要能力
- 语音转文字：POST /ai/audio/transcriptions，与 OpenAI Transcription API 一致，可使用 OpenAI 的 JS 或 Python SDK 调用。返回 duration、segments、text、words。示例使用模型 DISTIL_WHISPER_DISTIL_LARGE_V2。
- 聊天补全：POST /ai/chat/completions（已标注为废弃，建议改用 POST /v2/ai/openai/chat/completions）。必填 messages，可选参数包括 api_key_ref、best_of、early_stopping、enable_thinking、frequency_penalty、guided_choice、guided_json、guided_regex、length_penalty、logprobs、max_tokens、min_p、model、n、presence_penalty、response_format、seed、stop、stream、temperature、tool_choice、tools、top_logprobs、top_p、use_beam_search。
- 会话对话管理：列出、创建、检索、更新元数据、删除会话；为会话新增消息；获取会话消息（含 assistant 的工具调用）；获取会话洞察。
- 洞察模板与分组：列出/创建/获取/更新/删除洞察模板（insights）与洞察分组（insight-groups），以及将洞察分配到分组或从分组移除。
- 洞察聚合：GET /ai/conversations/conversation-insights/aggregates，按指定字段聚合会话洞察，返回 record_count。
- 嵌入：GET /ai/embeddings 按状态查询任务；POST /ai/embeddings 对 Telnyx Storage Bucket 中的文档执行嵌入，支持 PDF、HTML、txt/非结构化文本、json、csv 以及音频/视频（mp3、mp4、mpeg、mpga、m4a、wav、webm，最大 100MB），不匹配的文件将按非结构化文本尝试嵌入。
使用方式
错误处理建议在生产代码中始终捕获异常，示例使用 TelnyxServiceException：
import com.telnyx.sdk.errors.TelnyxServiceException;
try { var result = client.messages().send(params); } catch (TelnyxServiceException e) { System.err.println("API error " + e.statusCode() + ": " + e.getMessage()); if (e.statusCode() == 422) { System.err.println("Validation error — check required fields and formats"); } else if (e.statusCode() == 429) { Thread.sleep(1000); } }
常见错误码：401 API Key 无效、403 权限不足、404 资源未找到、422 校验错误（检查字段格式）、429 触发限流（建议指数退避重试）。
分页：列表方法返回一页，可用 .autoPager() 自动遍历：for (var item : page.autoPager()) { ... }；手动控制使用 .hasNextPage() 与 .nextPage()。
适用场景
- 用 Java 构建需要 Telnyx LLM 推理能力的应用。
- 对音频进行语音转文字，并进一步获取通话摘要与洞察。
- 管理 AI 对话会话与消息，维护对话记录。
- 定义洞察模板并分组，按字段聚合会话洞察。
- 对存储桶中的多类型文档或音视频做嵌入处理。
限制与说明
聊天补全端点 POST /ai/chat/completions 已标注为废弃，文档建议改用 POST /v2/ai/openai/chat/completions。嵌入音频/视频文件大小上限为 100MB。部分端点（如洞察分组、消息新增）仅列出必填与可选参数，具体返回字段已在文档中逐项标明。其他未在资料中出现的功能、收费、价格、平台支持与效果信息暂未提供。