一、接入点
| 请求方式 |
地址 |
POST |
https://api-maas.teleai.com.cn/v1/chat/completions |
Content-Type:application/json
二、鉴权
采用 Bearer Token 鉴权,在请求头中携带 API Key,请在 API Key 管理 页面,获取长效 API Key:
Authorization: Bearer <用户申请的API-KEY>
| 请求头 |
必填 |
说明 |
Content-Type |
是 |
内容类型,固定 application/json |
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 请求体
3.1.1 顶层字段
| 字段 |
类型 |
必填 |
说明 |
model |
string |
是 |
固定值 Xing4.0-29B-A4B、TeleChat3-438B-A24B 、Xing4.1-Preview |
messages |
array |
是 |
消息数组,按对话顺序排列,见 3.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 |
否 |
输出格式约束,见 3.1.3 |
seed |
integer |
否 |
随机种子,用于可复现采样 |
stop |
string / array |
否 |
停止序列 |
stream |
boolean |
否 |
是否流式返回,默认 false |
stream_options |
object |
否 |
流式附加选项,见 3.1.4 |
temperature |
number |
否 |
采样温度,范围 0~2 |
top_p |
number |
否 |
核采样,范围 0~1,默认 0.95 |
tools |
array |
否 |
工具定义数组,见 3.1.5 |
tool_choice |
string / object |
否 |
工具调用策略,见 3.1.6 |
parallel_tool_calls |
boolean |
否 |
是否允许并行调用多个工具,默认 true |
chat_template_kwargs |
object |
否 |
深度思考模式参数,默认开启,传入 {"enable_thinking": true} 启用深度思考,不建议关闭 |
reasoning_effort |
string |
否 |
思考强度,模型不支持 |
采样参数建议:
Xing4.0-29B-A4B:推荐使用 temperature =1.0 (默认), top_p =0.95 。
TeleChat3-438B-A24B:推荐使用 temperature =0.8 (默认), top_p =0.95 。
Xing4.1-Preview:
| 场景 |
temperature |
top_p |
repetition_penalty |
general |
0.8 |
0.95 |
1.05 |
code |
0.8 |
0.95 |
1.05 |
agent |
0.8 |
0.95 |
1.05 |
reasoning |
1.0 (默认) |
0.95 |
1.05 |
chat |
0.6 |
0.95 |
1.05 |
3.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 |
是 |
工具名称 |
3.1.3 response_format
| 结构 |
说明 |
Xing4.0-29B-A4B |
TeleChat3-438B-A24B |
Xing4.1-Preview |
{"type":"text"} |
默认文本输出 |
✅支持 |
✅支持 |
✅支持 |
{"type":"json_object"} |
JSON 对象输出(提示词中需包含「json」字样) |
✅支持 |
✅支持 |
✅支持 |
{"type":"json_schema","json_schema":{"name":"...","description":"...","schema":{...},"strict":true}} |
按 JSON Schema 约束输出 |
❌暂不支持 |
❌暂不支持 |
❌暂不支持 |
3.1.4 stream_options
| 字段 |
类型 |
说明 |
include_usage |
boolean |
为 true 时,流式末尾额外返回一个仅含 usage 的 chunk |
3.1.5 工具定义 tools[]
| 字段 |
类型 |
必填 |
说明 |
type |
string |
是 |
工具类型,当前为 function |
function |
object |
是 |
函数定义 |
function.name |
string |
是 |
函数名 |
function.description |
string |
否 |
函数描述 |
function.parameters |
object |
否 |
JSON Schema 形式的参数定义 |
3.1.6 tool_choice
- 字符串:
none(不调用工具)/ auto(自动决定)/ required(必须调用)
- 对象:
{"type":"function","function":{"name":"<函数名>"}} 指定具体函数
3.1.7 请求体示例
{
"model": "Xing4.1-Preview",
"messages": [
{ "role": "user", "content": "你好,一句话介绍一下你自己" }
],
"max_completion_tokens": 1024,
"stream": false
}
3.2 返回体
3.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 |
角色:assistant |
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 数 |
3.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 用量 |
3.2.3 非流式返回示例
{
"id": "9ace6a90a47502211e57bad9025e1adc",
"object": "chat.completion",
"created": 1794887187,
"model": "xing4.1-preview",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "您好!我是星辰语义大模型(Xing),由中电信人工智能科技有限公司研发……",
"reasoning_content": "用户要求用一句话介绍我自己。我需要简洁地介绍我的身份和功能……",
"reasoning": "用户要求用一句话介绍我自己。我需要简洁地介绍我的身份和功能……"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 93,
"total_tokens": 102,
"reasoning_tokens": 52
}
}
3.2.4 流式返回示例
data: {"id":"428f0555bb49b2946e114246c6f3a017","object":"chat.completion.chunk","created":1794907358,"model":"xing4.1-preview","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}
data: {"id":"428f0555bb49b2946e114246c6f3a017","object":"chat.completion.chunk","created":1794907358,"model":"xing4.1-preview","choices":[{"index":0,"delta":{"reasoning_content":"1","reasoning":"1"}}]}
...(思考内容逐增量下发,delta.reasoning / delta.reasoning_content)...
data: {"id":"428f0555bb49b2946e114246c6f3a017","object":"chat.completion.chunk","created":1794907359,"model":"xing4.1-preview","choices":[{"index":0,"delta":{"content":"我是星辰"}}]}
...(正文逐增量下发,delta.content)...
data: {"id":"428f0555bb49b2946e114246c6f3a017","object":"chat.completion.chunk","created":1794907360,"model":"xing4.1-preview","choices":[{"index":0,"delta":{},"finish_reason":"stop","matched_stop":1}]}
data: {"id":"428f0555bb49b2946e114246c6f3a017","object":"chat.completion.chunk","created":1794907360,"model":"xing4.1-preview","choices":[],"usage":{"prompt_tokens":11,"completion_tokens":347,"total_tokens":358,"reasoning_tokens":306}}
data: [DONE]
四、调用示例
4.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": "Xing4.0-29B-A4B",
"messages": [
{ "role": "user", "content": "你好,一句话介绍一下你自己" }
],
"stream": true
}'
4.2 Python
import requests
url = "https://api-maas.teleai.com.cn/v1/chat/completions"
api_key = "<用户申请的API-KEY>"
payload = {
"model": "model",
"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)
4.3 Java
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", "model",
"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()) {
// 非流式(stream=false 时):直接打印整个 body
// System.out.println(response.body().string());
// 流式(stream=true):逐行读取 SSE,event: 与 data: 成对解析,空行表示一个事件结束
try (okio.BufferedSource source = response.body().source()) {
for (String line; (line = source.readUtf8Line()) != null; ) {
if (line.isEmpty()) {
continue;
}
System.out.println(line);
}
}
}
}
}