TeleChat3-438B-A24B(算法编码：63650300010) - 兼容Responses 协议接口文档

协议类型：OpenAI Responses

---

一、接入点

环境	地址
公网	https://api-maas.teleai.com.cn/v1/responses
responses专属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 <API_KEY>，必填
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
input	string / array	是	用户输入，可为纯文本或输入项数组（见 4.1.2）
include	array	否	响应中额外包含的字段列表
instructions	string	否	系统指令，转成首条 system message
max_output_tokens	integer	否	生成的最大 token 数
max_tool_calls	integer	否	工具调用次数上限
metadata	object	否	键值对元数据
parallel_tool_calls	boolean	否	是否允许并行工具调用，默认true
reasoning	object	否	推理配置（effort / summary，见 4.1.5）
service_tier	string	否	容量档位（auto / default / flex / priority 等）
stream	boolean	否	是否流式返回，默认false
temperature	number	否	采样温度，范围0~`2，默认 0.8`
text	object	否	文本输出配置（format 结构化输出，见 4.1.5）
tool_choice	string / object	否	工具调用策略（见 4.1.4）
tools	array	否	工具定义数组，仅支持function 类型（见 4.1.3）
top_logprobs	integer	否	每步返回的最可能候选 token 数
top_p	number	否	核采样，范围0~`1，默认 0.95`
truncation	string	否	上下文截断策略：auto / disabled
user	string	否	终端用户标识

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

4.1.2 输入项类型 input[]

类型	结构	说明
消息	{"type":"message","role":"user","content":"..."}	消息项，role 取 system/user/assistant，content 为字符串或内容块数组
函数调用	{"type":"function_call","call_id":"...","name":"...","arguments":"..."}	助手已发出的函数调用
函数调用结果	{"type":"function_call_output","call_id":"...","output":"..."}	函数调用结果
推理	{"type":"reasoning","id":"...","summary":[...]}	引用/携带推理摘要

消息内容块类型 input[].content[] ：

类型	结构	说明
文本	{"type":"input_text","text":"..."}	文本；历史 assistant 消息中的output_text / text 块同样按文本处理

多模态分片不支持 ：input_image / input_audio / input_file 等内容块当前不支持，请勿传入。

请求体示例

{
    "model": "TeleChat3-438B-A24B",
    "input": [
        {
            "role": "user",
            "content": "你好，一句话介绍一下你自己"
        }
    ],
    "stream": true,
    "max_output_tokens": 1024,
    "temperature": 0.8,
    "top_p": 0.95
}

4.1.3 工具定义 tools[]

当前仅支持 function 类型工具，字段平铺在顶层（不嵌套 function 键）：

字段	类型	必填	说明
type	string	是	固定为function
name	string	是	工具名
description	string	否	工具描述
parameters	object	否	JSON Schema 形式的参数定义
strict	boolean	否	是否启用严格模式，按 Schema 约束参数生成

协议中的其他工具类型（namespace / custom / tool_search，以及 web_search / code_interpreter / file_search / computer_use_preview / mcp / image_generation 等内置工具）当前暂不支持。

4.1.4 tool_choice

• 字符串：auto / none / required（required 暂不强制生效）
• 对象：{"type":"function","name":"<工具名>"}，指定必须调用某个函数（暂不支持，返回 400）

4.1.5 reasoning / text（推理与结构化输出）

reasoning（推理配置） ：

字段	类型	说明
effort	string	推理深度：minimal / low / medium / high；传 none 关闭思考
summary	string	思考摘要展示方式：auto / concise / detailed

深度思考统一通过 reasoning.effort 控制，enable_thinking 等非标字段已废弃。
深度思考默认开启 ：不传 reasoning 参数时模型也会思考并输出 reasoning 项；传入 {"effort":"none"} 可关闭思考（输出仅含 message 项，无 reasoning 项）。

text.format（结构化输出） ：

type	说明
text	纯文本（默认）
json_object	返回合法 JSON
json_schema	返回符合 Schema 的 JSON；name / schema / strict / description 平铺在 format 内

示例 ：

{
    "model": "TeleChat3-438B-A24B",
    "input": "帮我生成一个北京三日游行程",
    "reasoning": { "effort": "high", "summary": "auto" },
    "text": {
        "format": {
            "type": "json_schema",
            "name": "trip_plan",
            "schema": {
                "type": "object",
                "properties": {
                    "days": { "type": "array", "items": { "type": "string" } }
                },
                "required": ["days"]
            }
        }
    }
}

4.2 返回体

非流式返回 ：

{
    "id": "resp_xxxxxxxx",
    "object": "response",
    "created_at": 1731691468,
    "status": "completed",
    "model": "TeleChat3-438B-A24B",
    "output": [
        {
            "type": "message",
            "id": "msg_xxxxxxxx",
            "role": "assistant",
            "status": "completed",
            "content": [
                {
                    "type": "output_text",
                    "text": "你好！我是星辰大模型，由中电信人工智能科技研发。",
                    "annotations": []
                }
            ]
        }
    ],
    "usage": {
        "input_tokens": 15,
        "input_tokens_details": { "cached_tokens": 0 },
        "output_tokens": 20,
        "output_tokens_details": { "reasoning_tokens": 0 },
        "total_tokens": 35
    }
}

返回字段说明 ：

字段	类型	说明
id	string	响应唯一 ID
object	string	固定为response
created_at	integer	创建时间（Unix 秒级时间戳）
status	string	响应状态（见下表）
error	object	错误信息。错误以 HTTP 错误体返回，统一嵌套于error 下（含 message / type / code）；成功响应中不含 error 字段
incomplete_details	object	未完成原因（status=incomplete），如 {"reason":"max_output_tokens"} / {"reason":"content_filter"}
model	string	实际使用的模型
output	array	输出项数组（见下表）
usage	object	token 用量
回显字段	—	instructions / max_output_tokens / metadata / parallel_tool_calls / reasoning / temperature / text / tool_choice / tools / top_p / truncation / user 等从原始请求拷回响应；tool_choice 未传时回显默认 "auto"

status 取值 ：

值	说明
completed	完成
in_progress	进行中
failed	失败
incomplete	未完成（如因 token 上限截断）
cancelled	已取消
queued	排队中

输出项类型 output[] ：

输出项按 type 区分，顺序为 reasoning → tool calls → message ：

类型	结构	说明
推理	{"type":"reasoning","id":"rs_...","summary":[{"type":"summary_text","text":"..."}]}	推理摘要（思维链以 summary 形式返回）
函数调用	{"type":"function_call","id":"fc_...","call_id":"...","name":"...","arguments":"..."}	函数调用，arguments 为字符串
消息	{"type":"message","id":"msg_...","role":"assistant","content":[...]}	助手消息

消息输出内容块 output[].content[] ：

类型	结构	说明
文本	{"type":"output_text","text":"...","annotations":[]}	文本回复
拒绝	{"type":"refusal","refusal":"..."}	拒绝说明

usage 字段 ：

字段	类型	说明
input_tokens	integer	输入 token 数（总输入语义，不减缓存）
input_tokens_details.cached_tokens	integer	命中缓存的输入 token 数
output_tokens	integer	输出 token 数
total_tokens	integer	总 token 数

流式返回（SSE，stream=true） ：

每个事件带 sequence_number（从 0 开始）。事件流结构：

response.created
response.in_progress
[ reasoning: output_item.added → reasoning_summary_part.added
             → reasoning_summary_text.delta ×N → *.done ]
[ text:      output_item.added → content_part.added
             → output_text.delta ×N → *.done ]
[ tool:      output_item.added → function_call_arguments.delta ×N → *.done ]
response.completed | response.incomplete | response.failed

事件类型说明 ：

事件	说明
response.created / response.in_progress	起始事件，output 为空数组（非 null）
response.output_item.added / .done	一个输出项的开始 / 结束
response.content_part.added / .done	message 输出项内内容块的开始 / 结束
response.output_text.delta / .done	文本增量 / 定稿
response.reasoning_summary_part.added / .done	推理摘要内容块的开始 / 结束
response.reasoning_summary_text.delta / .done	推理摘要文本增量 / 定稿
response.function_call_arguments.delta / .done	函数工具参数增量 / 定稿
response.completed / response.incomplete / response.failed	终态事件

示例 ：

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{...}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,"response":{...}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"type":"reasoning","id":"rs_xxx","summary":[]}}

event: response.reasoning_summary_part.added
data: {"type":"response.reasoning_summary_part.added","sequence_number":3,"output_index":0,"summary_index":0,"part":{"type":"summary_text","text":""}}

event: response.reasoning_summary_text.delta
data: {"type":"response.reasoning_summary_text.delta","sequence_number":4,"output_index":0,"summary_index":0,"delta":"用户在打招呼"}

event: response.reasoning_summary_text.done
data: {"type":"response.reasoning_summary_text.done","sequence_number":5,"output_index":0,"summary_index":0,"text":"用户在打招呼，需要简要自我介绍。"}

event: response.reasoning_summary_part.done
data: {"type":"response.reasoning_summary_part.done","sequence_number":6,"output_index":0,"summary_index":0,"part":{"type":"summary_text","text":"用户在打招呼，需要简要自我介绍。"}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":7,"output_index":0,"item":{...}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":8,"output_index":1,"item":{"type":"message","id":"msg_xxx","role":"assistant","status":"in_progress","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":9,"output_index":1,"content_index":0,"part":{"type":"output_text","text":"","annotations":null}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":10,"output_index":1,"content_index":0,"delta":"你好"}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":11,"output_index":1,"content_index":0,"text":"你好！我是星辰大模型。"}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":12,"output_index":1,"content_index":0,"part":{"type":"output_text","text":"你好！我是星辰大模型。","annotations":[]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":13,"output_index":1,"item":{...}}

event: response.completed
data: {"type":"response.completed","sequence_number":14,"response":{...}}

五、调用示例

5.1 curl

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

5.2 Python

import requests

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

payload = {
    "model": "TeleChat3-438B-A24B",
    "input": "你好，一句话介绍一下你自己",
    "stream": True,
}

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

# 流式解析 SSE（按 event / data 成对处理）
for line in resp.iter_lines(decode_unicode=True):
    if not line:
        continue
    print(line)

5.3 Java（使用 OkHttp + Jackson）

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

public class ResponsesExample {

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

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

        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
        }
    }
}