TeleChat3-438B(算法编码：63650300010) — OpenAI 协议接口文档

协议类型：OpenAI Chat Completions
版本：稳定版（max_tokens 已弃用，使用 max_completion_tokens）

---

一、接入点

环境	地址
公网	https://api-maas.teleai.com.cn/v1/chat/completions
openai专属baseurl	https://api-maas.teleai.com.cn/v1

• 请求方法 ：POST
• Content-Type ：application/json

---

二、鉴权

采用 Bearer Token 鉴权，在请求头中携带 API Key：

Authorization: Bearer <用户申请的API-KEY>

• API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。

请求头	说明
Authorization	Bearer ，必填
session-id	多轮对话场景下传入，不同 session 传入不同 session-id，非多轮对话场景请不要设置此字段
traceparent	W3C Trace Context 链路追踪头，格式{version}-{trace-id}-{parent-id}-{flags}，见下表

traceparent 字段说明 ：

字段	示例值	说明
version	00	W3C 版本号，默认00
trace-id	0af7651916cd43dd8448eb211c80319c	32 位十六进制，整条链路唯一 ID
parent-id	b7ad6b7169203331	16 位十六进制，当前请求 span ID
flags	01	默认01 即可

---

三、模型能力与模型限制

3.1 模型能力

能力项	支持情况	能力项	支持情况
输入模态	文本输入	输出模态	文本输出
模型体验	✅ 支持	结构化输出	✅ 支持
Function Call	✅ 支持	深度思考	✅ 支持
在线推理	✅ 支持	批量推理	❌ 不支持
显式缓存	❌ 不支持	隐式缓存	✅ 支持

3.2 模型限制

限制项	数值	限制项	数值
上下文长度	256K	最大思维链长度	128K
最大输入长度	192K	最大输入长度（思考模式下）	64K
最大输出长度	192K	最大输出长度（思考模式下）	64K

---

四、请求体与返回体

4.1 请求体

4.1.1 顶层字段

字段	类型	必填	说明
model	string	是	固定值TeleChat3-438B-A24B
messages	array	是	消息数组，按对话顺序排列，见 4.1.2
frequency_penalty	number	否	频率惩罚，范围-2.0~2.0，默认 0
logprobs	boolean	否	是否返回每个输出 token 的对数概率，默认false
top_logprobs	integer	否	每个 token 返回概率最高的前 N 个备选，0~20，需 logprobs=true
max_tokens	integer	否	已弃用 ，请改用 max_completion_tokens
max_completion_tokens	integer	否	生成的最大 token 数（含推理 token）
n	integer	否	生成的候选回复数，默认1
presence_penalty	number	否	存在惩罚，范围-2.0~2.0，默认 0
repetition_penalty	number	否	默认值：1.05, 取值范围 0~2。模型生成时连续序列中的重复度。提高该参数时可以降低模型生成的重复度，1.0表示不做惩罚。
response_format	object	否	输出格式约束，见 4.1.3
seed	integer	否	随机种子，用于可复现采样
stop	string / array	否	停止序列
stream	boolean	否	是否流式返回，默认false
stream_options	object	否	流式附加选项，见 4.1.4
temperature	number	否	采样温度，范围0~2，默认0.8
top_p	number	否	核采样，范围0~1，默认0.95
tools	array	否	工具定义数组，见 4.1.5
tool_choice	string / object	否	工具调用策略，见 4.1.6
parallel_tool_calls	boolean	否	是否允许并行调用多个工具，默认true
chat_template_kwargs	object	否	深度思考模式参数，默认开启，传入{"enable_thinking": true} 启用深度思考
reasoning_effort	string	否	推理力度，该模型不支持。

采样参数建议 ：推荐使用temperature =0.8， top_p =0.95。

4.1.2 消息体messages

消息对象 messages[]

字段	类型	必填	说明
role	string	是	角色：system / user / assistant / tool
content	string / array	是	消息内容，支持纯文本或内容块数组
name	string	否	参与者名称，用于区分同名角色
tool_calls	array	否	助手消息触发的工具调用（仅assistant）
tool_call_id	string	否	关联的工具调用 ID（tool 角色必填）

消息内容对象 content[]

字段	类型	必填	说明
type	string	是	分片类型，此模型仅支持text
text	string	是	文本内容

工具调用对象 tool_calls[]

字段	类型	必填	说明
id	string	是	工具ID
type	string	是	工具类型，目前仅支持function
function	object	是	工具定义

工具定义对象 function

字段	类型	必填	说明
arguments	string	是	JSON文本
name	string	是	工具名称

4.1.3 response_format

结构	说明
{"type":"text"}	默认文本输出
{"type":"json_object"}	JSON 对象输出（提示词中需包含「json」字样）
{"type":"json_schema","json_schema":{"name":"...","description":"...","schema":{...},"strict":true}}	按 JSON Schema 约束输出，暂不支持

4.1.4 stream_options

字段	类型	说明
include_usage	boolean	为true 时，流式末尾额外返回一个仅含 usage 的 chunk

4.1.5 工具定义 tools[]

字段	类型	必填	说明
type	string	是	工具类型，当前为function
function	object	是	函数定义
function.name	string	是	函数名
function.description	string	否	函数描述
function.parameters	object	否	JSON Schema 形式的参数定义

4.1.6 tool_choice

• 字符串：none（不调用工具）/ auto（自动决定）/ required（必须调用）
• 对象：{"type":"function","function":{"name":"<函数名>"}} 指定具体函数

4.2 返回体

4.2.1 顶层字段

字段	类型	说明
id	string	本次完成的唯一 ID
object	string	固定为chat.completion
created	integer	创建时间（Unix 秒级时间戳）
model	string	实际使用的模型
choices	array	结果数组
usage	object	token 用量

消息数组choices[]

字段	类型	说明
index	integer	候选序号
message	object	消息体
finish_reason	string	结束原因：stop（自然结束 / 命中 stop）、length（达上限）、tool_calls / function_call（转去调用工具）、content_filter（内容过滤）、null（未完成）、abort（中止）
logprobs	object	输出 token 的对数概率（开启logprobs 时返回）

消息对象 message

字段	类型	说明
role	string	角色：system / user / assistant / tool
content	string	文本内容
reasoning_content/reasoning	string	深度思考内容
tool_calls[]	object	{id, type:function, function:{name, arguments}}，arguments为JSON字符串

Token用量 usage

字段	类型	说明
prompt_tokens	integer	输入 token 数
completion_tokens	integer	输出 token 数
total_tokens	integer	总 token 数
prompt_tokens_details.cached_tokens	integer	命中的缓存 token 数

4.2.2 流式（SSE）响应字段

字段	类型	说明
id	string	本次完成的唯一 ID
object	string	固定为chat.completion.chunk
created	integer	创建时间（Unix 秒级时间戳）
model	string	实际使用的模型
choices	array	结果数组
choices[].index	integer	候选序号
choices[].delta	object	同返回体中choices[].message
choices[].finish_reason	string	结束原因：stop（自然结束 / 命中 stop）、length（达上限）、tool_calls / function_call（转去调用工具）、content_filter（内容过滤）、null（未完成）、abort（中止）
choices[].logprobs	object	输出 token 的对数概率（开启logprobs 时返回）
usage	object	token 用量

五、调用示例

5.1 curl

curl --location 'https://api-maas.teleai.com.cn/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <用户申请的API-KEY>' \
--data '{
    "model": "TeleChat3-438B-A24B",
    "messages": [
        { "role": "user", "content": "你好，一句话介绍一下你自己" }
    ],
    "stream": true
}'

5.2 Python

import requests

url = "https://api-maas.teleai.com.cn/v1/chat/completions"
api_key = "<用户申请的API-KEY>"

payload = {
    "model": "TeleChat3-438B-A24B",
    "messages": [{"role": "user", "content": "你好，一句话介绍一下你自己"}],
    "stream": True,
}

resp = requests.post(
    url,
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json=payload,
    stream=True,
)

# 流式解析 SSE
for line in resp.iter_lines(decode_unicode=True):
    if line and line.startswith("data:"):
        data = line[len("data:"):].strip()
        if data == "[DONE]":
            break
        print(data)

5.3 Java（使用 OkHttp + Jackson）

import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;

public class ChatCompletionsExample {

    public static void main(String[] args) throws Exception {
        String url = "https://api-maas.teleai.com.cn/v1/chat/completions";
        String apiKey = "<用户申请的API-KEY>";

        ObjectMapper mapper = new ObjectMapper();
        String json = mapper.writeValueAsString(java.util.Map.of(
            "model", "TeleChat3-438B-A24B",
            "messages", java.util.List.of(
                java.util.Map.of("role", "user", "content", "你好，一句话介绍一下你自己")
            ),
            "stream", true
        ));

        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
                .url(url)
                .addHeader("Content-Type", "application/json")
                .addHeader("Authorization", "Bearer " + apiKey)
                .post(RequestBody.create(json, MediaType.get("application/json")))
                .build();

        try (Response response = client.newCall(request).execute()) {
            // 非流式：直接打印 body
            System.out.println(response.body().string());
            // 流式：通过 ResponseBody.source() 逐行读取 SSE，遇 [DONE] 结束
        }
    }
}