体验中心
体验中国电信星辰大模型效果
| 请求方式 | 地址 |
|---|---|
POST |
https://api-maas.teleai.com.cn/v1/messages |
application/json采用 x-api-key 请求头鉴权,请在 API Key 管理 页面,获取长效 API Key:
x-api-key: <用户申请的API-KEY>
| 请求头 | 必填 | 说明 |
|---|---|---|
| Content-Type | 是 | 内容类型,固定 application/json |
| x-api-key | 是 | <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 即可 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 固定值 Xing4.0-29B-A4B、TeleChat3-438B-A24B 、Xing4.1-Preview |
messages |
array | 是 | 消息数组(见 3.1.2) |
system |
string / object | 否 | 系统提示词,独立于 messages(见 3.1.3) |
max_tokens |
integer | 是 | 生成的最大 token 数 |
stop_sequences |
array | 否 | 自定义停止序列 |
stream |
boolean | 否 | 是否流式返回,默认 false |
temperature |
number | 否 | 采样温度,范围 0.0 ~ 2.0 |
top_p |
number | 否 | 核采样,范围 0 ~ 1,默认 0.95 |
top_k |
integer | 否 | 忽略 |
tools |
array | 否 | 工具定义数组(见 3.1.4) |
tool_choice |
object | 否 | 工具调用策略(见 3.1.5) |
thinking |
object | 否 | 深度思考配置(见 3.1.6) |
output_config |
object | 否 | 输出参数设置(见 3.1.7) |
注意:
max_tokens为必填项,不传会报错。系统提示词通过顶层system字段传递,不放入messages。
采样参数建议:
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 |
|---|---|---|
general |
0.8 | 0.95 |
code |
0.8 | 0.95 |
agent |
0.8 | 0.95 |
reasoning |
1.0 (默认) | 0.95 |
chat |
0.6 | 0.95 |
消息对象 messages[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
role |
string | 是 | 角色:user / assistant |
content |
string / array | 是 | 消息内容,支持纯文本或内容块数组 |
输入内容块类型 content[]:
| 类型 | 结构 | 说明 |
|---|---|---|
| 文本 | {"type":"text","text":"..."} |
纯文本 |
| 工具调用 | {"type":"tool_use","id":"toolu_xxx","name":"get_weather","input":{...}} |
助手发起的工具调用 |
| 工具结果 | {"type":"tool_result","tool_use_id":"toolu_xxx","content":"..."} |
工具执行结果 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type |
string | 是 | 仅支持 text |
text |
string / array | 是 | 系统提示词文本 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name |
string | 是 | 工具名 |
description |
string | 否 | 工具描述 |
input_schema |
object | 是 | 输入参数的 JSON Schema |
| 结构 | 说明 |
|---|---|
{"type":"auto"} |
自动决定是否调用工具(默认) |
{"type":"any"} |
必须调用某个工具 |
{"type":"tool","name":"<工具名>"} |
强制调用指定工具 |
{"type":"none"} |
禁用工具 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type |
string | 否 | 是否开启深度思考,默认值是 enabled,不建议关闭,可选值:enabled、disabled |
budget_tokens |
integer | 否 | 控制深度思考 Token 数目 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
effort |
string | 否 | 可选值:none、minimal、low、medium、high、xhigh 或 max,模型暂不支持 |
format |
object | 否 | 模型暂不支持 |
{
"model": "Xing4.1-Preview",
"system": "你是乐于助人的助手。",
"messages": [
{ "role": "user", "content": "你好,一句话介绍一下你自己" }
],
"max_tokens": 1024,
"stream": true,
"temperature": 1.0,
"top_p": 0.95
}
返回字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 消息唯一 ID |
type |
string | 固定为 message |
role |
string | 固定为 assistant |
content |
array | 内容块数组 |
content[].type |
string | 内容块类型:thinking(思考内容)/text(文本)/ tool_use(工具调用) |
content[].thinking |
string | 当type为thinking时,think内容出现在此字段 |
content[].text |
string | 模型回复文本 |
content[].id |
string | 工具调用 ID(tool_use 类型) |
content[].name |
string | 工具名(tool_use 类型) |
content[].input |
object | 工具参数(tool_use 类型) |
model |
string | 实际使用的模型 |
stop_reason |
string | 结束原因(见下表) |
stop_sequence |
string / null | 命中的停止序列 |
usage.input_tokens |
integer | 输入 token 数 |
usage.cache_creation_input_tokens |
integer | 写入缓存的 token 数 |
usage.cache_read_input_tokens |
integer | 命中缓存的 token 数 |
usage.output_tokens |
integer | 输出 token 数 |
stop_reason 取值:
| 值 | 说明 |
|---|---|
end_turn |
正常结束 |
max_tokens |
达到 max_tokens 上限 |
tool_use |
模型发起工具调用 |
流式返回(SSE,stream=true)
流式返回按 event: / data: 成对出现:
流式事件类型:
| 事件 | 说明 |
|---|---|
message_start |
消息开始,携带完整 message 元信息 |
content_block_start |
内容块开始,携带 index 与 content_block |
content_block_delta |
内容块增量更新 |
content_block_stop |
内容块结束 |
message_delta |
消息级更新(stop_reason、usage) |
message_stop |
消息结束 |
ping |
心跳 |
error |
错误 |
content_block_delta 的 delta 类型:
| delta 类型 | 说明 |
|---|---|
text_delta |
文本增量 {"type":"text_delta","text":"..."} |
thinking_delta |
深度思考增量 {"type":"thinking_delta","thinking":"..."} |
input_json_delta |
工具参数增量 {"type":"input_json_delta","partial_json":"..."} |
{
"id": "msg_xxxxxxxx",
"type": "message",
"role": "assistant",
"model": "<model>",
"content": [
{ "type": "text", "text": "你好!我是星辰大模型,由中电信人工智能科技研发。" }
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 15,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 20
}
}
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","model":"xing4.1-preview","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":15,"output_tokens":1}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":20}}
event: message_stop
data: {"type":"message_stop"}
curl --location 'https://api-maas.teleai.com.cn/v1/messages' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <用户申请的API-KEY>' \
--data '{
"model": "model",
"messages": [
{ "role": "user", "content": "你好,一句话介绍一下你自己" }
],
"stream": true,
"max_tokens": 1024
}'
import requests
url = "https://api-maas.teleai.com.cn/v1/messages"
api_key = "<用户申请的API-KEY>"
payload = {
"model": "model",
"messages": [{"role": "user", "content": "你好,一句话介绍一下你自己"}],
"stream": True,
"max_tokens": 1024,
}
resp = requests.post(
url,
headers={
"x-api-key": api_key,
},
json=payload,
stream=True,
)
# 流式解析 SSE(按 event / data 成对处理)
for line in resp.iter_lines(decode_unicode=True):
if not line:
continue
print(line)
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
public class MessagesExample {
public static void main(String[] args) throws Exception {
String url = "https://api-maas.teleai.com.cn/v1/messages";
String apiKey = "<用户申请的API-KEY>";
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(java.util.Map.of(
"model", "Xing4.0-29B-A4B",
"messages", java.util.List.of(
java.util.Map.of("role", "user", "content", "你好,一句话介绍一下你自己")
),
"max_tokens", 1024,
"stream", true
));
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url(url)
.addHeader("Content-Type", "application/json")
.addHeader("x-api-key", 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);
}
}
}
}
}