Back to Details

telnyx-ai-inference-javascript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Ai Inference - JavaScript

Telnyx AI 推理 - JavaScript

Installation

安装

bash
npm install telnyx
bash
npm install telnyx

Setup

配置

javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
All examples below assume 
client
is already initialized as shown above.
javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // 这是默认配置，可省略
});
以下所有示例都默认
client
已经按照上述方式完成初始化。

Error Handling

错误处理

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:
javascript
try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}
Common error codes: 
401
invalid API key, 
403
insufficient permissions, 
404
resource not found, 
422
validation error (check field formats), 
429
rate limited (retry with exponential backoff).
所有API调用都可能失败，原因包括网络错误、速率限制(429)、校验错误(422)，或是鉴权错误(401)。生产环境代码中请务必做好错误处理：
javascript
try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: 触发速率限制 — 等待后使用指数退避策略重试
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}
常见错误码：
401
API密钥无效，
403
权限不足，
404
资源不存在，
422
校验错误（请检查字段格式），
429
触发速率限制（请使用指数退避策略重试）。

Important Notes

重要说明

  • Pagination: List methods return an auto-paginating iterator. Use 
    for await (const item of result) { ... }
    to iterate through all pages automatically.
  • 分页： 列表类方法返回支持自动分页的迭代器，你可以使用
    for await (const item of result) { ... }
    自动遍历所有分页数据。

Transcribe speech to text

语音转文字

Transcribe speech to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.
POST /ai/audio/transcriptions
javascript
const response = await client.ai.audio.transcribe({ model: 'distil-whisper/distil-large-v2' });

console.log(response.text);
Returns: 
duration
(number), 
segments
(array[object]), 
text
(string)
将语音转录为文字。该接口与OpenAI Transcription API兼容，可直接搭配OpenAI的JS或Python SDK使用。
POST /ai/audio/transcriptions
javascript
const response = await client.ai.audio.transcribe({ model: 'distil-whisper/distil-large-v2' });

console.log(response.text);
返回参数：
duration
（数字）、
segments
（对象数组）、
text
（字符串）

Create a chat completion

创建聊天补全

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.
POST /ai/chat/completions
— Required: 
messages
Optional: 
api_key_ref
(string), 
best_of
(integer), 
early_stopping
(boolean), 
enable_thinking
(boolean), 
frequency_penalty
(number), 
guided_choice
(array[string]), 
guided_json
(object), 
guided_regex
(string), 
length_penalty
(number), 
logprobs
(boolean), 
max_tokens
(integer), 
min_p
(number), 
model
(string), 
n
(number), 
presence_penalty
(number), 
response_format
(object), 
stream
(boolean), 
temperature
(number), 
tool_choice
(enum: none, auto, required), 
tools
(array[object]), 
top_logprobs
(integer), 
top_p
(number), 
use_beam_search
(boolean)
javascript
const response = await client.ai.chat.createCompletion({
  messages: [
    { role: 'system', content: 'You are a friendly chatbot.' },
    { role: 'user', content: 'Hello, world!' },
  ],
});

console.log(response);
与大语言模型对话。该接口与OpenAI Chat Completions API兼容，可直接搭配OpenAI的JS或Python SDK使用。
POST /ai/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
（对象）、
stream
（布尔值）、
temperature
（数字）、
tool_choice
（枚举值：none, auto, required）、
tools
（对象数组）、
top_logprobs
（整数）、
top_p
（数字）、
use_beam_search
（布尔值）
javascript
const response = await client.ai.chat.createCompletion({
  messages: [
    { role: 'system', content: 'You are a friendly chatbot.' },
    { role: 'user', content: 'Hello, world!' },
  ],
});

console.log(response);

List conversations

对话列表查询

Retrieve a list of all AI conversations configured by the user. Supports PostgREST-style query parameters for filtering. Examples are included for the standard metadata fields, but you can filter on any field in the metadata JSON object.
GET /ai/conversations
javascript
const conversations = await client.ai.conversations.list();

console.log(conversations.data);
Returns: 
created_at
(date-time), 
id
(uuid), 
last_message_at
(date-time), 
metadata
(object), 
name
(string)
获取用户配置的所有AI对话列表。支持PostgREST风格的查询参数进行过滤，我们提供了标准元数据字段的过滤示例，你也可以对元数据JSON对象中的任意字段进行过滤。
GET /ai/conversations
javascript
const conversations = await client.ai.conversations.list();

console.log(conversations.data);
返回参数：
created_at
（日期时间）、
id
（uuid）、
last_message_at
（日期时间）、
metadata
（对象）、
name
（字符串）

Create a conversation

创建对话

Create a new AI Conversation.
POST /ai/conversations
Optional: 
metadata
(object), 
name
(string)
javascript
const conversation = await client.ai.conversations.create();

console.log(conversation.id);
Returns: 
created_at
(date-time), 
id
(uuid), 
last_message_at
(date-time), 
metadata
(object), 
name
(string)
创建一个新的AI对话。
POST /ai/conversations
可选参数：
metadata
（对象）、
name
（字符串）
javascript
const conversation = await client.ai.conversations.create();

console.log(conversation.id);
返回参数：
created_at
（日期时间）、
id
（uuid）、
last_message_at
（日期时间）、
metadata
（对象）、
name
（字符串）

Get Insight Template Groups

获取洞察模板分组

Get all insight groups
GET /ai/conversations/insight-groups
javascript
// Automatically fetches more pages as needed.
for await (const insightTemplateGroup of client.ai.conversations.insightGroups.retrieveInsightGroups()) {
  console.log(insightTemplateGroup.id);
}
Returns: 
created_at
(date-time), 
description
(string), 
id
(uuid), 
insights
(array[object]), 
name
(string), 
webhook
(string)
获取所有洞察分组
GET /ai/conversations/insight-groups
javascript
// 需要时自动拉取更多分页数据
for await (const insightTemplateGroup of client.ai.conversations.insightGroups.retrieveInsightGroups()) {
  console.log(insightTemplateGroup.id);
}
返回参数：
created_at
（日期时间）、
description
（字符串）、
id
（uuid）、
insights
（对象数组）、
name
（字符串）、
webhook
（字符串）

Create Insight Template Group

创建洞察模板分组

Create a new insight group
POST /ai/conversations/insight-groups
— Required: 
name
Optional: 
description
(string), 
webhook
(string)
javascript
const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.insightGroups({
  name: 'my-resource',
});

console.log(insightTemplateGroupDetail.data);
Returns: 
created_at
(date-time), 
description
(string), 
id
(uuid), 
insights
(array[object]), 
name
(string), 
webhook
(string)
创建一个新的洞察分组
POST /ai/conversations/insight-groups
— 必填参数：
name
可选参数：
description
（字符串）、
webhook
（字符串）
javascript
const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.insightGroups({
  name: 'my-resource',
});

console.log(insightTemplateGroupDetail.data);
返回参数：
created_at
（日期时间）、
description
（字符串）、
id
（uuid）、
insights
（对象数组）、
name
（字符串）、
webhook
（字符串）

Get Insight Template Group

查询洞察模板分组详情

Get insight group by ID
GET /ai/conversations/insight-groups/{group_id}
javascript
const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateGroupDetail.data);
Returns: 
created_at
(date-time), 
description
(string), 
id
(uuid), 
insights
(array[object]), 
name
(string), 
webhook
(string)
根据ID查询指定洞察分组
GET /ai/conversations/insight-groups/{group_id}
javascript
const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateGroupDetail.data);
返回参数：
created_at
（日期时间）、
description
（字符串）、
id
（uuid）、
insights
（对象数组）、
name
（字符串）、
webhook
（字符串）

Update Insight Template Group

更新洞察模板分组

Update an insight template group
PUT /ai/conversations/insight-groups/{group_id}
Optional: 
description
(string), 
name
(string), 
webhook
(string)
javascript
const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateGroupDetail.data);
Returns: 
created_at
(date-time), 
description
(string), 
id
(uuid), 
insights
(array[object]), 
name
(string), 
webhook
(string)
更新指定洞察模板分组
PUT /ai/conversations/insight-groups/{group_id}
可选参数：
description
（字符串）、
name
（字符串）、
webhook
（字符串）
javascript
const insightTemplateGroupDetail = await client.ai.conversations.insightGroups.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateGroupDetail.data);
返回参数：
created_at
（日期时间）、
description
（字符串）、
id
（uuid）、
insights
（对象数组）、
name
（字符串）、
webhook
（字符串）

Delete Insight Template Group

删除洞察模板分组

Delete insight group by ID
DELETE /ai/conversations/insight-groups/{group_id}
javascript
await client.ai.conversations.insightGroups.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
根据ID删除指定洞察分组
DELETE /ai/conversations/insight-groups/{group_id}
javascript
await client.ai.conversations.insightGroups.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

Assign Insight Template To Group

给分组分配洞察模板

Assign an insight to a group
POST /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign
javascript
await client.ai.conversations.insightGroups.insights.assign(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  { group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
);
给指定分组分配洞察模板
POST /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign
javascript
await client.ai.conversations.insightGroups.insights.assign(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  { group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
);

Unassign Insight Template From Group

从分组移除洞察模板

Remove an insight from a group
DELETE /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign
javascript
await client.ai.conversations.insightGroups.insights.deleteUnassign(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  { group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
);
从指定分组中移除洞察模板
DELETE /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign
javascript
await client.ai.conversations.insightGroups.insights.deleteUnassign(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  { group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
);

Get Insight Templates

获取洞察模板列表

Get all insights
GET /ai/conversations/insights
javascript
// Automatically fetches more pages as needed.
for await (const insightTemplate of client.ai.conversations.insights.list()) {
  console.log(insightTemplate.id);
}
Returns: 
created_at
(date-time), 
id
(uuid), 
insight_type
(enum: custom, default), 
instructions
(string), 
json_schema
(object), 
name
(string), 
webhook
(string)
获取所有洞察模板
GET /ai/conversations/insights
javascript
// 需要时自动拉取更多分页数据
for await (const insightTemplate of client.ai.conversations.insights.list()) {
  console.log(insightTemplate.id);
}
返回参数：
created_at
（日期时间）、
id
（uuid）、
insight_type
（枚举值：custom, default）、
instructions
（字符串）、
json_schema
（对象）、
name
（字符串）、
webhook
（字符串）

Create Insight Template

创建洞察模板

Create a new insight
POST /ai/conversations/insights
— Required: 
instructions
, 
name
Optional: 
json_schema
(object), 
webhook
(string)
javascript
const insightTemplateDetail = await client.ai.conversations.insights.create({
  instructions: 'You are a helpful assistant.',
  name: 'my-resource',
});

console.log(insightTemplateDetail.data);
Returns: 
created_at
(date-time), 
id
(uuid), 
insight_type
(enum: custom, default), 
instructions
(string), 
json_schema
(object), 
name
(string), 
webhook
(string)
创建一个新的洞察模板
POST /ai/conversations/insights
— 必填参数：
instructions
, 
name
可选参数：
json_schema
（对象）、
webhook
（字符串）
javascript
const insightTemplateDetail = await client.ai.conversations.insights.create({
  instructions: 'You are a helpful assistant.',
  name: 'my-resource',
});

console.log(insightTemplateDetail.data);
返回参数：
created_at
（日期时间）、
id
（uuid）、
insight_type
（枚举值：custom, default）、
instructions
（字符串）、
json_schema
（对象）、
name
（字符串）、
webhook
（字符串）

Get Insight Template

查询洞察模板详情

Get insight by ID
GET /ai/conversations/insights/{insight_id}
javascript
const insightTemplateDetail = await client.ai.conversations.insights.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateDetail.data);
Returns: 
created_at
(date-time), 
id
(uuid), 
insight_type
(enum: custom, default), 
instructions
(string), 
json_schema
(object), 
name
(string), 
webhook
(string)
根据ID查询指定洞察模板
GET /ai/conversations/insights/{insight_id}
javascript
const insightTemplateDetail = await client.ai.conversations.insights.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateDetail.data);
返回参数：
created_at
（日期时间）、
id
（uuid）、
insight_type
（枚举值：custom, default）、
instructions
（字符串）、
json_schema
（对象）、
name
（字符串）、
webhook
（字符串）

Update Insight Template

更新洞察模板

Update an insight template
PUT /ai/conversations/insights/{insight_id}
Optional: 
instructions
(string), 
json_schema
(object), 
name
(string), 
webhook
(string)
javascript
const insightTemplateDetail = await client.ai.conversations.insights.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateDetail.data);
Returns: 
created_at
(date-time), 
id
(uuid), 
insight_type
(enum: custom, default), 
instructions
(string), 
json_schema
(object), 
name
(string), 
webhook
(string)
更新指定洞察模板
PUT /ai/conversations/insights/{insight_id}
可选参数：
instructions
（字符串）、
json_schema
（对象）、
name
（字符串）、
webhook
（字符串）
javascript
const insightTemplateDetail = await client.ai.conversations.insights.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(insightTemplateDetail.data);
返回参数：
created_at
（日期时间）、
id
（uuid）、
insight_type
（枚举值：custom, default）、
instructions
（字符串）、
json_schema
（对象）、
name
（字符串）、
webhook
（字符串）

Delete Insight Template

删除洞察模板

Delete insight by ID
DELETE /ai/conversations/insights/{insight_id}
javascript
await client.ai.conversations.insights.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
根据ID删除指定洞察模板
DELETE /ai/conversations/insights/{insight_id}
javascript
await client.ai.conversations.insights.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

Get a conversation

查询对话详情

Retrieve a specific AI conversation by its ID.
GET /ai/conversations/{conversation_id}
javascript
const conversation = await client.ai.conversations.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(conversation.data);
Returns: 
created_at
(date-time), 
id
(uuid), 
last_message_at
(date-time), 
metadata
(object), 
name
(string)
根据ID查询指定AI对话的详情。
GET /ai/conversations/{conversation_id}
javascript
const conversation = await client.ai.conversations.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(conversation.data);
返回参数：
created_at
（日期时间）、
id
（uuid）、
last_message_at
（日期时间）、
metadata
（对象）、
name
（字符串）

Update conversation metadata

更新对话元数据

Update metadata for a specific conversation.
PUT /ai/conversations/{conversation_id}
Optional: 
metadata
(object)
javascript
const conversation = await client.ai.conversations.update('550e8400-e29b-41d4-a716-446655440000');

console.log(conversation.data);
Returns: 
created_at
(date-time), 
id
(uuid), 
last_message_at
(date-time), 
metadata
(object), 
name
(string)
更新指定对话的元数据。
PUT /ai/conversations/{conversation_id}
可选参数：
metadata
（对象）
javascript
const conversation = await client.ai.conversations.update('550e8400-e29b-41d4-a716-446655440000');

console.log(conversation.data);
返回参数：
created_at
（日期时间）、
id
（uuid）、
last_message_at
（日期时间）、
metadata
（对象）、
name
（字符串）

Delete a conversation

删除对话

Delete a specific conversation by its ID.
DELETE /ai/conversations/{conversation_id}
javascript
await client.ai.conversations.delete('550e8400-e29b-41d4-a716-446655440000');
根据ID删除指定对话。
DELETE /ai/conversations/{conversation_id}
javascript
await client.ai.conversations.delete('550e8400-e29b-41d4-a716-446655440000');

Get insights for a conversation

获取对话洞察

Retrieve insights for a specific conversation
GET /ai/conversations/{conversation_id}/conversations-insights
javascript
const response = await client.ai.conversations.retrieveConversationsInsights('550e8400-e29b-41d4-a716-446655440000');

console.log(response.data);
Returns: 
conversation_insights
(array[object]), 
created_at
(date-time), 
id
(string), 
status
(enum: pending, in_progress, completed, failed)
获取指定对话的洞察数据
GET /ai/conversations/{conversation_id}/conversations-insights
javascript
const response = await client.ai.conversations.retrieveConversationsInsights('550e8400-e29b-41d4-a716-446655440000');

console.log(response.data);
返回参数：
conversation_insights
（对象数组）、
created_at
（日期时间）、
id
（字符串）、
status
（枚举值：pending, in_progress, completed, failed）

Create Message

创建消息

Add a new message to the conversation. Used to insert a new messages to a conversation manually ( without using chat endpoint )
POST /ai/conversations/{conversation_id}/message
— Required: 
role
Optional: 
content
(string), 
metadata
(object), 
name
(string), 
sent_at
(date-time), 
tool_call_id
(string), 
tool_calls
(array[object]), 
tool_choice
(object)
javascript
await client.ai.conversations.addMessage('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { role: 'user' });
给对话添加一条新消息，用于手动向对话中插入消息（无需使用聊天接口）
POST /ai/conversations/{conversation_id}/message
— 必填参数：
role
可选参数：
content
（字符串）、
metadata
（对象）、
name
（字符串）、
sent_at
（日期时间）、
tool_call_id
（字符串）、
tool_calls
（对象数组）、
tool_choice
（对象）
javascript
await client.ai.conversations.addMessage('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { role: 'user' });

Get conversation messages

获取对话消息列表

Retrieve messages for a specific conversation, including tool calls made by the assistant.
GET /ai/conversations/{conversation_id}/messages
javascript
const messages = await client.ai.conversations.messages.list('550e8400-e29b-41d4-a716-446655440000');

console.log(messages.data);
Returns: 
created_at
(date-time), 
role
(enum: user, assistant, tool), 
sent_at
(date-time), 
text
(string), 
tool_calls
(array[object])
获取指定对话的消息列表，包括助手发起的工具调用记录。
GET /ai/conversations/{conversation_id}/messages
javascript
const messages = await client.ai.conversations.messages.list('550e8400-e29b-41d4-a716-446655440000');

console.log(messages.data);
返回参数：
created_at
（日期时间）、
role
（枚举值：user, assistant, tool）、
sent_at
（日期时间）、
text
（字符串）、
tool_calls
（对象数组）

Get Tasks by Status

按状态查询任务

Retrieve tasks for the user that are either 
queued
, 
processing
, 
failed
, 
success
or 
partial_success
based on the query string. Defaults to 
queued
and 
processing
.
GET /ai/embeddings
javascript
const embeddings = await client.ai.embeddings.list();

console.log(embeddings.data);
Returns: 
bucket
(string), 
created_at
(date-time), 
finished_at
(date-time), 
status
(enum: queued, processing, success, failure, partial_success), 
task_id
(string), 
task_name
(string), 
user_id
(string)
根据查询字符串获取用户的任务，状态可选项为
queued
、
processing
、
failed
、
success
或
partial_success
，默认返回
queued
和
processing
状态的任务。
GET /ai/embeddings
javascript
const embeddings = await client.ai.embeddings.list();

console.log(embeddings.data);
返回参数：
bucket
（字符串）、
created_at
（日期时间）、
finished_at
（日期时间）、
status
（枚举值：queued, processing, success, failure, partial_success）、
task_id
（字符串）、
task_name
（字符串）、
user_id
（字符串）

Embed documents

文档嵌入

Perform embedding on a Telnyx Storage Bucket using an embedding model. The current supported file types are:
  • PDF
  • HTML
  • txt/unstructured text files
  • json
  • csv
  • audio / video (mp3, mp4, mpeg, mpga, m4a, wav, or webm ) - Max of 100mb file size. Any files not matching the above types will be attempted to be embedded as unstructured text.
POST /ai/embeddings
— Required: 
bucket_name
Optional: 
document_chunk_overlap_size
(integer), 
document_chunk_size
(integer), 
embedding_model
(object), 
loader
(object)
javascript
const embeddingResponse = await client.ai.embeddings.create({ bucket_name: 'bucket_name' });

console.log(embeddingResponse.data);
Returns: 
created_at
(string), 
finished_at
(string | null), 
status
(string), 
task_id
(uuid), 
task_name
(string), 
user_id
(uuid)
使用嵌入模型对Telnyx存储桶中的文档进行嵌入处理，当前支持的文件类型如下：
  • PDF
  • HTML
  • txt/非结构化文本文件
  • json
  • csv
  • 音频/视频（mp3、mp4、mpeg、mpga、m4a、wav或webm）- 最大文件大小100MB。所有不符合上述类型的文件将尝试作为非结构化文本进行嵌入处理。
POST /ai/embeddings
— 必填参数：
bucket_name
可选参数：
document_chunk_overlap_size
（整数）、
document_chunk_size
（整数）、
embedding_model
（对象）、
loader
（对象）
javascript
const embeddingResponse = await client.ai.embeddings.create({ bucket_name: 'bucket_name' });

console.log(embeddingResponse.data);
返回参数：
created_at
（字符串）、
finished_at
（字符串 | null）、
status
（字符串）、
task_id
（uuid）、
task_name
（字符串）、
user_id
（uuid）

List embedded buckets

查询已嵌入存储桶列表

Get all embedding buckets for a user.
GET /ai/embeddings/buckets
javascript
const buckets = await client.ai.embeddings.buckets.list();

console.log(buckets.data);
Returns: 
buckets
(array[string])
获取用户所有已完成嵌入的存储桶。
GET /ai/embeddings/buckets
javascript
const buckets = await client.ai.embeddings.buckets.list();

console.log(buckets.data);
返回参数：
buckets
（字符串数组）

Get file-level embedding statuses for a bucket

查询存储桶下文件的嵌入状态

Get all embedded files for a given user bucket, including their processing status.
GET /ai/embeddings/buckets/{bucket_name}
javascript
const bucket = await client.ai.embeddings.buckets.retrieve('bucket_name');

console.log(bucket.data);
Returns: 
created_at
(date-time), 
error_reason
(string), 
filename
(string), 
last_embedded_at
(date-time), 
status
(string), 
updated_at
(date-time)
获取指定用户存储桶下所有已嵌入文件的处理状态。
GET /ai/embeddings/buckets/{bucket_name}
javascript
const bucket = await client.ai.embeddings.buckets.retrieve('bucket_name');

console.log(bucket.data);
返回参数：
created_at
（日期时间）、
error_reason
（字符串）、
filename
（字符串）、
last_embedded_at
（日期时间）、
status
（字符串）、
updated_at
（日期时间）

Disable AI for an Embedded Bucket

禁用存储桶的AI功能

Deletes an entire bucket's embeddings and disables the bucket for AI-use, returning it to normal storage pricing.
DELETE /ai/embeddings/buckets/{bucket_name}
javascript
await client.ai.embeddings.buckets.delete('bucket_name');
删除整个存储桶的嵌入数据并禁用该存储桶的AI功能，恢复为普通存储计费标准。
DELETE /ai/embeddings/buckets/{bucket_name}
javascript
await client.ai.embeddings.buckets.delete('bucket_name');

Search for documents

文档检索

Perform a similarity search on a Telnyx Storage Bucket, returning the most similar 
num_docs
document chunks to the query. Currently the only available distance metric is cosine similarity which will return a 
distance
between 0 and 1. The lower the distance, the more similar the returned document chunks are to the query.
POST /ai/embeddings/similarity-search
— Required: 
bucket_name
, 
query
Optional: 
num_of_docs
(integer)
javascript
const response = await client.ai.embeddings.similaritySearch({
  bucket_name: 'bucket_name',
  query: 'What is Telnyx?',
});

console.log(response.data);
Returns: 
distance
(number), 
document_chunk
(string), 
metadata
(object)
在Telnyx存储桶中执行相似度搜索，返回与查询最相似的
num_docs
个文档块。当前唯一可用的距离度量标准是余弦相似度，返回的
distance
值介于0到1之间，值越低表示返回的文档块与查询相似度越高。
POST /ai/embeddings/similarity-search
— 必填参数：
bucket_name
, 
query
可选参数：
num_of_docs
（整数）
javascript
const response = await client.ai.embeddings.similaritySearch({
  bucket_name: 'bucket_name',
  query: 'What is Telnyx?',
});

console.log(response.data);
返回参数：
distance
（数字）、
document_chunk
（字符串）、
metadata
（对象）

Embed URL content

URL内容嵌入

Embed website content from a specified URL, including child pages up to 5 levels deep within the same domain. The process crawls and loads content from the main URL and its linked pages into a Telnyx Cloud Storage bucket.
POST /ai/embeddings/url
— Required: 
url
, 
bucket_name
javascript
const embeddingResponse = await client.ai.embeddings.url({
  bucket_name: 'bucket_name',
  url: 'https://example.com/resource',
});

console.log(embeddingResponse.data);
Returns: 
created_at
(string), 
finished_at
(string | null), 
status
(string), 
task_id
(uuid), 
task_name
(string), 
user_id
(uuid)
对指定URL的网站内容进行嵌入处理，包括同域名下最多5级深度的子页面。该流程会爬取主URL及其链接页面的内容，并加载到Telnyx云存储桶中。
POST /ai/embeddings/url
— 必填参数：
url
, 
bucket_name
javascript
const embeddingResponse = await client.ai.embeddings.url({
  bucket_name: 'bucket_name',
  url: 'https://example.com/resource',
});

console.log(embeddingResponse.data);
返回参数：
created_at
（字符串）、
finished_at
（字符串 | null）、
status
（字符串）、
task_id
（uuid）、
task_name
（字符串）、
user_id
（uuid）

Get an embedding task's status

查询嵌入任务状态

Check the status of a current embedding task. Will be one of the following:
  • queued
    - Task is waiting to be picked up by a worker
  • processing
    - The embedding task is running
  • success
    - Task completed successfully and the bucket is embedded
  • failure
    - Task failed and no files were embedded successfully
  • partial_success
    - Some files were embedded successfully, but at least one failed
GET /ai/embeddings/{task_id}
javascript
const embedding = await client.ai.embeddings.retrieve('task_id');

console.log(embedding.data);
Returns: 
created_at
(string), 
finished_at
(string), 
status
(enum: queued, processing, success, failure, partial_success), 
task_id
(uuid), 
task_name
(string)
查看当前嵌入任务的状态，可能的状态如下：
  • queued
    - 任务正在等待 worker 处理
  • processing
    - 嵌入任务正在运行中
  • success
    - 任务执行成功，存储桶已完成嵌入
  • failure
    - 任务执行失败，没有文件成功完成嵌入
  • partial_success
    - 部分文件成功完成嵌入，但至少有一个文件处理失败
GET /ai/embeddings/{task_id}
javascript
const embedding = await client.ai.embeddings.retrieve('task_id');

console.log(embedding.data);
返回参数：
created_at
（字符串）、
finished_at
（字符串）、
status
（枚举值：queued, processing, success, failure, partial_success）、
task_id
（uuid）、
task_name
（字符串）

List fine tuning jobs

查询微调任务列表

Retrieve a list of all fine tuning jobs created by the user.
GET /ai/fine_tuning/jobs
javascript
const jobs = await client.ai.fineTuning.jobs.list();

console.log(jobs.data);
Returns: 
created_at
(integer), 
finished_at
(integer | null), 
hyperparameters
(object), 
id
(string), 
model
(string), 
organization_id
(string), 
status
(enum: queued, running, succeeded, failed, cancelled), 
trained_tokens
(integer | null), 
training_file
(string)
获取用户创建的所有微调任务列表。
GET /ai/fine_tuning/jobs
javascript
const jobs = await client.ai.fineTuning.jobs.list();

console.log(jobs.data);
返回参数：
created_at
（整数）、
finished_at
（整数 | null）、
hyperparameters
（对象）、
id
（字符串）、
model
（字符串）、
organization_id
（字符串）、
status
（枚举值：queued, running, succeeded, failed, cancelled）、
trained_tokens
（整数 | null）、
training_file
（字符串）

Create a fine tuning job

创建微调任务

Create a new fine tuning job.
POST /ai/fine_tuning/jobs
— Required: 
model
, 
training_file
Optional: 
hyperparameters
(object), 
suffix
(string)
javascript
const fineTuningJob = await client.ai.fineTuning.jobs.create({
  model: 'openai/gpt-4o',
  training_file: 'training_file',
});

console.log(fineTuningJob.id);
Returns: 
created_at
(integer), 
finished_at
(integer | null), 
hyperparameters
(object), 
id
(string), 
model
(string), 
organization_id
(string), 
status
(enum: queued, running, succeeded, failed, cancelled), 
trained_tokens
(integer | null), 
training_file
(string)
创建一个新的微调任务。
POST /ai/fine_tuning/jobs
— 必填参数：
model
, 
training_file
可选参数：
hyperparameters
（对象）、
suffix
（字符串）
javascript
const fineTuningJob = await client.ai.fineTuning.jobs.create({
  model: 'openai/gpt-4o',
  training_file: 'training_file',
});

console.log(fineTuningJob.id);
返回参数：
created_at
（整数）、
finished_at
（整数 | null）、
hyperparameters
（对象）、
id
（字符串）、
model
（字符串）、
organization_id
（字符串）、
status
（枚举值：queued, running, succeeded, failed, cancelled）、
trained_tokens
（整数 | null）、
training_file
（字符串）

Get a fine tuning job

查询微调任务详情

Retrieve a fine tuning job by 
job_id
.
GET /ai/fine_tuning/jobs/{job_id}
javascript
const fineTuningJob = await client.ai.fineTuning.jobs.retrieve('job_id');

console.log(fineTuningJob.id);
Returns: 
created_at
(integer), 
finished_at
(integer | null), 
hyperparameters
(object), 
id
(string), 
model
(string), 
organization_id
(string), 
status
(enum: queued, running, succeeded, failed, cancelled), 
trained_tokens
(integer | null), 
training_file
(string)
根据
job_id
查询指定微调任务。
GET /ai/fine_tuning/jobs/{job_id}
javascript
const fineTuningJob = await client.ai.fineTuning.jobs.retrieve('job_id');

console.log(fineTuningJob.id);
返回参数：
created_at
（整数）、
finished_at
（整数 | null）、
hyperparameters
（对象）、
id
（字符串）、
model
（字符串）、
organization_id
（字符串）、
status
（枚举值：queued, running, succeeded, failed, cancelled）、
trained_tokens
（整数 | null）、
training_file
（字符串）

Cancel a fine tuning job

取消微调任务

Cancel a fine tuning job.
POST /ai/fine_tuning/jobs/{job_id}/cancel
javascript
const fineTuningJob = await client.ai.fineTuning.jobs.cancel('job_id');

console.log(fineTuningJob.id);
Returns: 
created_at
(integer), 
finished_at
(integer | null), 
hyperparameters
(object), 
id
(string), 
model
(string), 
organization_id
(string), 
status
(enum: queued, running, succeeded, failed, cancelled), 
trained_tokens
(integer | null), 
training_file
(string)
取消指定微调任务。
POST /ai/fine_tuning/jobs/{job_id}/cancel
javascript
const fineTuningJob = await client.ai.fineTuning.jobs.cancel('job_id');

console.log(fineTuningJob.id);
返回参数：
created_at
（整数）、
finished_at
（整数 | null）、
hyperparameters
（对象）、
id
（字符串）、
model
（字符串）、
organization_id
（字符串）、
status
（枚举值：queued, running, succeeded, failed, cancelled）、
trained_tokens
（整数 | null）、
training_file
（字符串）

Get available models

获取可用模型列表

This endpoint returns a list of Open Source and OpenAI models that are available for use. Note: Model 
id
's will be in the form 
{source}/{model_name}
. For example 
openai/gpt-4
or 
mistralai/Mistral-7B-Instruct-v0.1
consistent with HuggingFace naming conventions.
GET /ai/models
javascript
const response = await client.ai.retrieveModels();

console.log(response.data);
Returns: 
created
(integer), 
id
(string), 
object
(string), 
owned_by
(string)
该接口返回所有可用的开源模型和OpenAI模型。注意：模型
id
格式为
{source}/{model_name}
，例如
openai/gpt-4
或
mistralai/Mistral-7B-Instruct-v0.1
，与HuggingFace的命名规范一致。
GET /ai/models
javascript
const response = await client.ai.retrieveModels();

console.log(response.data);
返回参数：
created
（整数）、
id
（字符串）、
object
（字符串）、
owned_by
（字符串）

Create embeddings

创建嵌入向量

Creates an embedding vector representing the input text. This endpoint is compatible with the OpenAI Embeddings API and may be used with the OpenAI JS or Python SDK by setting the base URL to 
https://api.telnyx.com/v2/ai/openai
.
POST /ai/openai/embeddings
— Required: 
input
, 
model
Optional: 
dimensions
(integer), 
encoding_format
(enum: float, base64), 
user
(string)
javascript
const response = await client.ai.openai.embeddings.createEmbeddings({
  input: 'The quick brown fox jumps over the lazy dog',
  model: 'thenlper/gte-large',
});

console.log(response.data);
Returns: 
data
(array[object]), 
model
(string), 
object
(string), 
usage
(object)
生成表示输入文本的嵌入向量。该接口与OpenAI Embeddings API兼容，将基础URL设置为
https://api.telnyx.com/v2/ai/openai
即可直接搭配OpenAI的JS或Python SDK使用。
POST /ai/openai/embeddings
— 必填参数：
input
, 
model
可选参数：
dimensions
（整数）、
encoding_format
（枚举值：float, base64）、
user
（字符串）
javascript
const response = await client.ai.openai.embeddings.createEmbeddings({
  input: 'The quick brown fox jumps over the lazy dog',
  model: 'thenlper/gte-large',
});

console.log(response.data);
返回参数：
data
（对象数组）、
model
（字符串）、
object
（字符串）、
usage
（对象）

List embedding models

查询嵌入模型列表

Returns a list of available embedding models. This endpoint is compatible with the OpenAI Models API format.
GET /ai/openai/embeddings/models
javascript
const response = await client.ai.openai.embeddings.listEmbeddingModels();

console.log(response.data);
Returns: 
created
(integer), 
id
(string), 
object
(string), 
owned_by
(string)
返回所有可用的嵌入模型列表，该接口兼容OpenAI Models API格式。
GET /ai/openai/embeddings/models
javascript
const response = await client.ai.openai.embeddings.listEmbeddingModels();

console.log(response.data);
返回参数：
created
（整数）、
id
（字符串）、
object
（字符串）、
owned_by
（字符串）

Summarize file content

文件内容摘要

Generate a summary of a file's contents. Supports the following text formats:
  • PDF, HTML, txt, json, csv
Supports the following media formats (billed for both the transcription and summary):
  • flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm
  • Up to 100 MB
POST /ai/summarize
— Required: 
bucket
, 
filename
Optional: 
system_prompt
(string)
javascript
const response = await client.ai.summarize({ bucket: 'my-bucket', filename: 'data.csv' });

console.log(response.data);
Returns: 
summary
(string)
生成文件内容的摘要，支持以下文本格式：
  • PDF、HTML、txt、json、csv
支持以下媒体格式（按转录和摘要分别计费）：
  • flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav、webm
  • 最大文件大小100 MB
POST /ai/summarize
— 必填参数：
bucket
, 
filename
可选参数：
system_prompt
（字符串）
javascript
const response = await client.ai.summarize({ bucket: 'my-bucket', filename: 'data.csv' });

console.log(response.data);
返回参数：
summary
（字符串）

Get all Speech to Text batch report requests

获取所有语音转文字批量报告请求

Retrieves all Speech to Text batch report requests for the authenticated user
GET /legacy/reporting/batch_detail_records/speech_to_text
javascript
const speechToTexts = await client.legacy.reporting.batchDetailRecords.speechToText.list();

console.log(speechToTexts.data);
Returns: 
created_at
(date-time), 
download_link
(string), 
end_date
(date-time), 
id
(string), 
record_type
(string), 
start_date
(date-time), 
status
(enum: PENDING, COMPLETE, FAILED, EXPIRED)
获取已认证用户的所有语音转文字批量报告请求
GET /legacy/reporting/batch_detail_records/speech_to_text
javascript
const speechToTexts = await client.legacy.reporting.batchDetailRecords.speechToText.list();

console.log(speechToTexts.data);
返回参数：
created_at
（日期时间）、
download_link
（字符串）、
end_date
（日期时间）、
id
（字符串）、
record_type
（字符串）、
start_date
（日期时间）、
status
（枚举值：PENDING, COMPLETE, FAILED, EXPIRED）

Create a new Speech to Text batch report request

创建语音转文字批量报告请求

Creates a new Speech to Text batch report request with the specified filters
POST /legacy/reporting/batch_detail_records/speech_to_text
— Required: 
start_date
, 
end_date
javascript
const speechToText = await client.legacy.reporting.batchDetailRecords.speechToText.create({
  end_date: '2020-07-01T00:00:00-06:00',
  start_date: '2020-07-01T00:00:00-06:00',
});

console.log(speechToText.data);
Returns: 
created_at
(date-time), 
download_link
(string), 
end_date
(date-time), 
id
(string), 
record_type
(string), 
start_date
(date-time), 
status
(enum: PENDING, COMPLETE, FAILED, EXPIRED)
使用指定的筛选条件创建新的语音转文字批量报告请求
POST /legacy/reporting/batch_detail_records/speech_to_text
— 必填参数：
start_date
, 
end_date
javascript
const speechToText = await client.legacy.reporting.batchDetailRecords.speechToText.create({
  end_date: '2020-07-01T00:00:00-06:00',
  start_date: '2020-07-01T00:00:00-06:00',
});

console.log(speechToText.data);
返回参数：
created_at
（日期时间）、
download_link
（字符串）、
end_date
（日期时间）、
id
（字符串）、
record_type
（字符串）、
start_date
（日期时间）、
status
（枚举值：PENDING, COMPLETE, FAILED, EXPIRED）

Get a specific Speech to Text batch report request

查询语音转文字批量报告请求详情

Retrieves a specific Speech to Text batch report request by ID
GET /legacy/reporting/batch_detail_records/speech_to_text/{id}
javascript
const speechToText = await client.legacy.reporting.batchDetailRecords.speechToText.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(speechToText.data);
Returns: 
created_at
(date-time), 
download_link
(string), 
end_date
(date-time), 
id
(string), 
record_type
(string), 
start_date
(date-time), 
status
(enum: PENDING, COMPLETE, FAILED, EXPIRED)
根据ID查询指定的语音转文字批量报告请求
GET /legacy/reporting/batch_detail_records/speech_to_text/{id}
javascript
const speechToText = await client.legacy.reporting.batchDetailRecords.speechToText.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(speechToText.data);
返回参数：
created_at
（日期时间）、
download_link
（字符串）、
end_date
（日期时间）、
id
（字符串）、
record_type
（字符串）、
start_date
（日期时间）、
status
（枚举值：PENDING, COMPLETE, FAILED, EXPIRED）

Delete a Speech to Text batch report request

删除语音转文字批量报告请求

Deletes a specific Speech to Text batch report request by ID
DELETE /legacy/reporting/batch_detail_records/speech_to_text/{id}
javascript
const speechToText = await client.legacy.reporting.batchDetailRecords.speechToText.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(speechToText.data);
Returns: 
created_at
(date-time), 
download_link
(string), 
end_date
(date-time), 
id
(string), 
record_type
(string), 
start_date
(date-time), 
status
(enum: PENDING, COMPLETE, FAILED, EXPIRED)
根据ID删除指定的语音转文字批量报告请求
DELETE /legacy/reporting/batch_detail_records/speech_to_text/{id}
javascript
const speechToText = await client.legacy.reporting.batchDetailRecords.speechToText.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(speechToText.data);
返回参数：
created_at
（日期时间）、
download_link
（字符串）、
end_date
（日期时间）、
id
（字符串）、
record_type
（字符串）、
start_date
（日期时间）、
status
（枚举值：PENDING, COMPLETE, FAILED, EXPIRED）

Get speech to text usage report

获取语音转文字使用报告

Generate and fetch speech to text usage report synchronously. This endpoint will both generate and fetch the speech to text report over a specified time period.
GET /legacy/reporting/usage_reports/speech_to_text
javascript
const response = await client.legacy.reporting.usageReports.retrieveSpeechToText();

console.log(response.data);
Returns: 
data
(object)
同步生成并获取语音转文字使用报告，该接口可在指定时间范围内生成并获取语音转文字报告。
GET /legacy/reporting/usage_reports/speech_to_text
javascript
const response = await client.legacy.reporting.usageReports.retrieveSpeechToText();

console.log(response.data);
返回参数：
data
（对象）

Generate speech from text

文字转语音

Generate synthesized speech audio from text input. Returns audio in the requested format (binary audio stream, base64-encoded JSON, or an audio URL for later retrieval). Authentication is provided via the standard 
Authorization: Bearer
header.
POST /text-to-speech/speech
Optional: 
aws
(object), 
azure
(object), 
disable_cache
(boolean), 
elevenlabs
(object), 
language
(string), 
minimax
(object), 
output_type
(enum: binary_output, base64_output), 
provider
(enum: aws, telnyx, azure, elevenlabs, minimax, rime, resemble), 
resemble
(object), 
rime
(object), 
telnyx
(object), 
text
(string), 
text_type
(enum: text, ssml), 
voice
(string), 
voice_settings
(object)
javascript
const response = await client.textToSpeech.generate();

console.log(response.base64_audio);
Returns: 
base64_audio
(string)
从文本输入生成合成语音音频，按请求格式返回结果（二进制音频流、base64编码的JSON，或是可后续获取的音频URL）。通过标准的
Authorization: Bearer
请求头进行鉴权。
POST /text-to-speech/speech
可选参数：
aws
（对象）、
azure
（对象）、
disable_cache
（布尔值）、
elevenlabs
（对象）、
language
（字符串）、
minimax
（对象）、
output_type
（枚举值：binary_output, base64_output）、
provider
（枚举值：aws, telnyx, azure, elevenlabs, minimax, rime, resemble）、
resemble
（对象）、
rime
（对象）、
telnyx
（对象）、
text
（字符串）、
text_type
（枚举值：text, ssml）、
voice
（字符串）、
voice_settings
（对象）
javascript
const response = await client.textToSpeech.generate();

console.log(response.base64_audio);
返回参数：
base64_audio
（字符串）

List available voices

查询可用音色列表

Retrieve a list of available voices from one or all TTS providers. When 
provider
is specified, returns voices for that provider only. Otherwise, returns voices from all providers.
GET /text-to-speech/voices
javascript
const response = await client.textToSpeech.listVoices();

console.log(response.voices);
Returns: 
voices
(array[object])
获取单个或所有TTS服务商的可用音色列表。指定
provider
参数时仅返回该服务商的音色，否则返回所有服务商的音色。
GET /text-to-speech/voices
javascript
const response = await client.textToSpeech.listVoices();

console.log(response.voices);
返回参数：
voices
（对象数组）