Back to Details

telnyx-ai-inference-python

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
<!-- 由Telnyx OpenAPI规范自动生成，请勿编辑。 -->

Telnyx Ai Inference - Python

Telnyx AI推理 - Python

Installation

安装

bash
pip install telnyx
bash
pip install telnyx

Setup

配置

python
import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
All examples below assume 
client
is already initialized as shown above.
python
import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("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:
python
import telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
    # 429: rate limited — wait and retry with exponential backoff
    import time
    time.sleep(1)  # Check Retry-After header for actual delay
except telnyx.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("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)。在生产代码中请务必做好错误处理：
python
import telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("网络错误 — 检查网络连接并重试")
except telnyx.RateLimitError:
    # 429: 触发速率限制 — 等待后采用指数退避策略重试
    import time
    time.sleep(1)  # 可查看Retry-After响应头获取实际需要等待的时长
except telnyx.APIStatusError as e:
    print(f"API错误 {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("校验错误 — 检查必填字段和格式是否正确")
常见错误码：
401
API密钥无效，
403
权限不足，
404
资源不存在，
422
校验错误（检查字段格式），
429
触发速率限制（采用指数退避策略重试）。

Important Notes

重要说明

  • Pagination: List methods return an auto-paginating iterator. Use 
    for item in page_result:
    to iterate through all pages automatically.
  • 分页： 列表类方法返回自动分页迭代器，使用
    for item in page_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
python
response = client.ai.audio.transcribe(
    model="distil-whisper/distil-large-v2",
)
print(response.text)
Returns: 
duration
(number), 
segments
(array[object]), 
text
(string)
语音转文字转录。该接口与OpenAI转录API兼容，可通过OpenAI JS或Python SDK调用。
POST /ai/audio/transcriptions
python
response = client.ai.audio.transcribe(
    model="distil-whisper/distil-large-v2",
)
print(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)
python
response = client.ai.chat.create_completion(
    messages=[{
        "role": "system",
        "content": "You are a friendly chatbot.",
    }, {
        "role": "user",
        "content": "Hello, world!",
    }],
)
print(response)
与大语言模型对话。该接口与OpenAI聊天补全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
（布尔值）
python
response = client.ai.chat.create_completion(
    messages=[{
        "role": "system",
        "content": "You are a friendly chatbot.",
    }, {
        "role": "user",
        "content": "Hello, world!",
    }],
)
print(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
python
conversations = client.ai.conversations.list()
print(conversations.data)
Returns: 
created_at
(date-time), 
id
(uuid), 
last_message_at
(date-time), 
metadata
(object), 
name
(string)
获取用户配置的所有AI会话列表，支持PostgREST风格的查询参数进行筛选。文档中提供了标准元数据字段的筛选示例，你也可以基于元数据JSON对象中的任意字段进行筛选。
GET /ai/conversations
python
conversations = client.ai.conversations.list()
print(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)
python
conversation = client.ai.conversations.create()
print(conversation.id)
Returns: 
created_at
(date-time), 
id
(uuid), 
last_message_at
(date-time), 
metadata
(object), 
name
(string)
创建一个新的AI会话。
POST /ai/conversations
可选参数：
metadata
（对象）、
name
（字符串）
python
conversation = client.ai.conversations.create()
print(conversation.id)
返回值：
created_at
（日期时间）、
id
（uuid）、
last_message_at
（日期时间）、
metadata
（对象）、
name
（字符串）

Get Insight Template Groups

获取洞察模板分组

Get all insight groups
GET /ai/conversations/insight-groups
python
page = client.ai.conversations.insight_groups.retrieve_insight_groups()
page = page.data[0]
print(page.id)
Returns: 
created_at
(date-time), 
description
(string), 
id
(uuid), 
insights
(array[object]), 
name
(string), 
webhook
(string)
获取所有洞察分组
GET /ai/conversations/insight-groups
python
page = client.ai.conversations.insight_groups.retrieve_insight_groups()
page = page.data[0]
print(page.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)
python
insight_template_group_detail = client.ai.conversations.insight_groups.insight_groups(
    name="my-resource",
)
print(insight_template_group_detail.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
（字符串）
python
insight_template_group_detail = client.ai.conversations.insight_groups.insight_groups(
    name="my-resource",
)
print(insight_template_group_detail.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}
python
insight_template_group_detail = client.ai.conversations.insight_groups.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_group_detail.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}
python
insight_template_group_detail = client.ai.conversations.insight_groups.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_group_detail.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)
python
insight_template_group_detail = client.ai.conversations.insight_groups.update(
    group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_group_detail.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
（字符串）
python
insight_template_group_detail = client.ai.conversations.insight_groups.update(
    group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_group_detail.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}
python
client.ai.conversations.insight_groups.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
根据ID删除洞察分组
DELETE /ai/conversations/insight-groups/{group_id}
python
client.ai.conversations.insight_groups.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
python
client.ai.conversations.insight_groups.insights.assign(
    insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
将一个洞察分配到分组中
POST /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign
python
client.ai.conversations.insight_groups.insights.assign(
    insight_id="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
python
client.ai.conversations.insight_groups.insights.delete_unassign(
    insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
将一个洞察从分组中移除
DELETE /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign
python
client.ai.conversations.insight_groups.insights.delete_unassign(
    insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)

Get Insight Templates

获取洞察模板列表

Get all insights
GET /ai/conversations/insights
python
page = client.ai.conversations.insights.list()
page = page.data[0]
print(page.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
python
page = client.ai.conversations.insights.list()
page = page.data[0]
print(page.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)
python
insight_template_detail = client.ai.conversations.insights.create(
    instructions="You are a helpful assistant.",
    name="my-resource",
)
print(insight_template_detail.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
（字符串）
python
insight_template_detail = client.ai.conversations.insights.create(
    instructions="You are a helpful assistant.",
    name="my-resource",
)
print(insight_template_detail.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}
python
insight_template_detail = client.ai.conversations.insights.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_detail.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}
python
insight_template_detail = client.ai.conversations.insights.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_detail.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)
python
insight_template_detail = client.ai.conversations.insights.update(
    insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_detail.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
（字符串）
python
insight_template_detail = client.ai.conversations.insights.update(
    insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_detail.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}
python
client.ai.conversations.insights.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
根据ID删除洞察
DELETE /ai/conversations/insights/{insight_id}
python
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}
python
conversation = client.ai.conversations.retrieve(
    "conversation_id",
)
print(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}
python
conversation = client.ai.conversations.retrieve(
    "conversation_id",
)
print(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)
python
conversation = client.ai.conversations.update(
    conversation_id="550e8400-e29b-41d4-a716-446655440000",
)
print(conversation.data)
Returns: 
created_at
(date-time), 
id
(uuid), 
last_message_at
(date-time), 
metadata
(object), 
name
(string)
更新指定会话的元数据。
PUT /ai/conversations/{conversation_id}
可选参数：
metadata
（对象）
python
conversation = client.ai.conversations.update(
    conversation_id="550e8400-e29b-41d4-a716-446655440000",
)
print(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}
python
client.ai.conversations.delete(
    "conversation_id",
)
根据ID删除指定会话。
DELETE /ai/conversations/{conversation_id}
python
client.ai.conversations.delete(
    "conversation_id",
)

Get insights for a conversation

获取会话洞察

Retrieve insights for a specific conversation
GET /ai/conversations/{conversation_id}/conversations-insights
python
response = client.ai.conversations.retrieve_conversations_insights(
    "conversation_id",
)
print(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
python
response = client.ai.conversations.retrieve_conversations_insights(
    "conversation_id",
)
print(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)
python
client.ai.conversations.add_message(
    conversation_id="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
（对象）
python
client.ai.conversations.add_message(
    conversation_id="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
python
messages = client.ai.conversations.messages.list(
    "conversation_id",
)
print(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
python
messages = client.ai.conversations.messages.list(
    "conversation_id",
)
print(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
python
embeddings = client.ai.embeddings.list()
print(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
python
embeddings = client.ai.embeddings.list()
print(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)
python
embedding_response = client.ai.embeddings.create(
    bucket_name="my-bucket",
)
print(embedding_response.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
（对象）
python
embedding_response = client.ai.embeddings.create(
    bucket_name="my-bucket",
)
print(embedding_response.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
python
buckets = client.ai.embeddings.buckets.list()
print(buckets.data)
Returns: 
buckets
(array[string])
获取用户所有已完成嵌入的存储桶。
GET /ai/embeddings/buckets
python
buckets = client.ai.embeddings.buckets.list()
print(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}
python
bucket = client.ai.embeddings.buckets.retrieve(
    "bucket_name",
)
print(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}
python
bucket = client.ai.embeddings.buckets.retrieve(
    "bucket_name",
)
print(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}
python
client.ai.embeddings.buckets.delete(
    "bucket_name",
)
删除存储桶的全部嵌入数据，禁用该存储桶的AI功能，恢复为普通存储计费模式。
DELETE /ai/embeddings/buckets/{bucket_name}
python
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)
python
response = client.ai.embeddings.similarity_search(
    bucket_name="my-bucket",
    query="What is Telnyx?",
)
print(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
（整数）
python
response = client.ai.embeddings.similarity_search(
    bucket_name="my-bucket",
    query="What is Telnyx?",
)
print(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
python
embedding_response = client.ai.embeddings.url(
    bucket_name="my-bucket",
    url="https://example.com/resource",
)
print(embedding_response.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
python
embedding_response = client.ai.embeddings.url(
    bucket_name="my-bucket",
    url="https://example.com/resource",
)
print(embedding_response.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}
python
embedding = client.ai.embeddings.retrieve(
    "task_id",
)
print(embedding.data)
Returns: 
created_at
(string), 
finished_at
(string), 
status
(enum: queued, processing, success, failure, partial_success), 
task_id
(uuid), 
task_name
(string)
查询当前嵌入任务的状态，状态包括以下几种：
  • queued
    - 任务正在等待工作节点处理
  • processing
    - 嵌入任务正在运行
  • success
    - 任务执行成功，存储桶已完成嵌入
  • failure
    - 任务失败，没有文件成功完成嵌入
  • partial_success
    - 部分文件嵌入成功，但至少有一个文件失败
GET /ai/embeddings/{task_id}
python
embedding = client.ai.embeddings.retrieve(
    "task_id",
)
print(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
python
jobs = client.ai.fine_tuning.jobs.list()
print(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
python
jobs = client.ai.fine_tuning.jobs.list()
print(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)
python
fine_tuning_job = client.ai.fine_tuning.jobs.create(
    model="openai/gpt-4o",
    training_file="training-data.jsonl",
)
print(fine_tuning_job.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
（字符串）
python
fine_tuning_job = client.ai.fine_tuning.jobs.create(
    model="openai/gpt-4o",
    training_file="training-data.jsonl",
)
print(fine_tuning_job.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}
python
fine_tuning_job = client.ai.fine_tuning.jobs.retrieve(
    "job_id",
)
print(fine_tuning_job.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}
python
fine_tuning_job = client.ai.fine_tuning.jobs.retrieve(
    "job_id",
)
print(fine_tuning_job.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
python
fine_tuning_job = client.ai.fine_tuning.jobs.cancel(
    "job_id",
)
print(fine_tuning_job.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
python
fine_tuning_job = client.ai.fine_tuning.jobs.cancel(
    "job_id",
)
print(fine_tuning_job.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
python
response = client.ai.retrieve_models()
print(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
python
response = client.ai.retrieve_models()
print(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)
python
response = client.ai.openai.embeddings.create_embeddings(
    input="The quick brown fox jumps over the lazy dog",
    model="thenlper/gte-large",
)
print(response.data)
Returns: 
data
(array[object]), 
model
(string), 
object
(string), 
usage
(object)
生成表示输入文本的嵌入向量。该接口与OpenAI嵌入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
（字符串）
python
response = client.ai.openai.embeddings.create_embeddings(
    input="The quick brown fox jumps over the lazy dog",
    model="thenlper/gte-large",
)
print(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
python
response = client.ai.openai.embeddings.list_embedding_models()
print(response.data)
Returns: 
created
(integer), 
id
(string), 
object
(string), 
owned_by
(string)
返回可用的嵌入模型列表，该接口兼容OpenAI模型API格式。
GET /ai/openai/embeddings/models
python
response = client.ai.openai.embeddings.list_embedding_models()
print(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)
python
response = client.ai.summarize(
    bucket="my-bucket",
    filename="data.csv",
)
print(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
（字符串）
python
response = client.ai.summarize(
    bucket="my-bucket",
    filename="data.csv",
)
print(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
python
speech_to_texts = client.legacy.reporting.batch_detail_records.speech_to_text.list()
print(speech_to_texts.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
python
speech_to_texts = client.legacy.reporting.batch_detail_records.speech_to_text.list()
print(speech_to_texts.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
python
from datetime import datetime

speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.create(
    end_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
    start_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
)
print(speech_to_text.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
python
from datetime import datetime

speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.create(
    end_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
    start_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
)
print(speech_to_text.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}
python
speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(speech_to_text.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}
python
speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.retrieve(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(speech_to_text.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}
python
speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(speech_to_text.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}
python
speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.delete(
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(speech_to_text.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
python
response = client.legacy.reporting.usage_reports.retrieve_speech_to_text()
print(response.data)
Returns: 
data
(object)
同步生成并获取语音转文字使用报告。该接口可在指定时间范围内生成并获取语音转文字报告。
GET /legacy/reporting/usage_reports/speech_to_text
python
response = client.legacy.reporting.usage_reports.retrieve_speech_to_text()
print(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)
python
response = client.text_to_speech.generate()
print(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
（对象）
python
response = client.text_to_speech.generate()
print(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
python
response = client.text_to_speech.list_voices()
print(response.voices)
Returns: 
voices
(array[object])
获取一个或所有TTS服务商的可用音色列表。指定
provider
参数时仅返回该服务商的音色，否则返回所有服务商的音色。
GET /text-to-speech/voices
python
response = client.text_to_speech.list_voices()
print(response.voices)
返回值：
voices
（对象数组）