ChatNut 5.6 API 参考

统一的 HTTP 接口，覆盖三个模型规格。协议遵循业界通用规范，现有客户端仅需更换服务地址即可接入。

快速开始

安装官方 SDK：

pip install chestnut        # Python
npm install @chestnut/sdk   # Node.js

发起首次调用：

from chestnut import ChestNut

client = ChestNut(api_key="ck-live-...")

resp = client.messages.create(
    model="chatnut-5.6-terra",
    max_tokens=512,
    messages=[
        {"role": "user", "content": "简述稀疏专家架构的核心思想"}
    ],
)
print(resp.content[0].text)

鉴权

所有请求须在 Authorization 头中携带 Bearer 前缀与密钥：

curl https://api.chestnut.ai/v1/messages \
  -H "Authorization: Bearer ck-live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chatnut-5.6-terra",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "你好"}]
  }'

密钥于控制台 → API Keys 创建，仅在创建时完整显示一次。
请勿将密钥写入前端代码或提交至代码仓库；一旦泄露应立即吊销。
建议为每个环境创建独立密钥，账单将按密钥维度拆分统计。

模型选择

模型	定位	激活参数	上下文窗口	建议用途
`chatnut-5.6-sol`	旗舰	41.3T	2,097,152	复杂推理、长文档分析、多步智能体编排
`chatnut-5.6-terra`	通用	8.6T	1,048,576	通用问答、代码辅助、内容生成
`chatnut-5.6-luna`	轻量	1.19T	262,144	分类、抽取、意图路由等轻量任务

建议自 chatnut-5.6-terra 起步，如效果不足再切换至更高规格。三个规格接口完全一致，仅需更换模型名称。

消息接口

POST /v1/messages

参数	类型	必填	说明
`model`	string	是	模型名
`messages`	array	是	对话历史，`role` 取值为 `user` 或 `assistant`
`max_tokens`	int	是	输出 tokens 上限
`system`	string	否	系统提示词
`temperature`	float	否	取值区间 0–1，默认 0.7
`stream`	bool	否	是否启用流式传输，默认 false
`tools`	array	否	可供模型调用的工具定义

{
  "id": "msg_01H8xKp2mQ",
  "type": "message",
  "role": "assistant",
  "model": "chatnut-5.6-terra",
  "content": [{ "type": "text", "text": "稀疏专家架构的核心在于……" }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 18, "output_tokens": 96 }
}

流式传输

将 stream 置为 true 后，服务端以 SSE 逐帧推送。首 token 延迟中位数为 214 ms。

with client.messages.stream(
    model="chatnut-5.6-terra",
    max_tokens=1024,
    messages=[{"role": "user", "content": "撰写一段产品发布公告"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

事件序列：

event: message_start
event: content_block_delta   ← 可能有很多个
event: content_block_stop
event: message_delta
event: message_stop

连接中断后可携带 last_event_id 重连续传，已生成内容不重复计费。

工具调用

声明工具后，模型将在需要时返回 tool_use，由调用方执行并回填结果。单次响应可返回多个工具调用以便并行执行。

tools = [{
    "name": "get_weather",
    "description": "查询某地当前天气",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

resp = client.messages.create(
    model="chatnut-5.6-sol",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "北京今日是否需要携带雨具"}],
)

如需强制结构化输出，可传入 response_format={"type": "json_schema", "schema": ...}。语法约束在解码阶段生效，可保证输出结构合法。

批量接口

非实时任务可提交至 POST /v1/batches，按 50% 计费，承诺 24 小时内完成。单批次上限 100,000 条请求。

batch = client.batches.create(
    requests=[
        {"custom_id": "row-1", "params": {...}},
        {"custom_id": "row-2", "params": {...}},
    ]
)
print(batch.id, batch.status)   # batch_01J9…  in_progress

速率限制

方案	请求 / 分钟	输入 tokens / 分钟	并发流
标准免费版	20	40,000	2
专业版	4,000	800,000	64
企业版	按预留算力	按预留算力	不限

触发限流将返回 429，响应头 retry-after 给出建议等待秒数。请实现指数退避策略，避免持续重试。

错误码

HTTP	type	含义	处理建议
400	`invalid_request`	请求参数不合法	依据错误信息修正参数
401	`authentication_error`	密钥无效或已吊销	更换有效密钥
403	`permission_error`	密钥无权访问该模型	核查密钥权限配置
404	`not_found`	模型或资源不存在	核对模型名称
413	`request_too_large`	请求体超出上限	拆分输入后重试
429	`rate_limit`	触发速率限制	按 `retry-after` 退避重试
429	`quota_exceeded`	额度已耗尽	完成充值或升级订阅
500	`internal_error`	服务端内部异常	携带 request-id 联系技术支持
503	`capacity_exceeded`	区域算力已达上限	稍后重试或切换区域
504	`inference_timeout`	推理响应超时	重试或降低 max_tokens
529	`model_overloaded`	模型整体过载	指数退避后重试

每个响应均包含 request-id 头。提交故障工单时请一并提供该标识，否则无法定位对应调用。

常见问题

请求数据是否会用于模型训练？

不会。API 请求默认零保留，内容不落盘亦不进入训练集。如需贡献数据，可在账户设置中显式开启。

可以用满 2,097,152 tokens 上下文吗？

可以，输入 tokens 照常计费。建议配合前缀缓存使用，命中部分按 10% 计价。

相同输入为何返回不同结果？

temperature 大于 0 时输出具有随机性。如需可复现结果，请将其设为 0 并固定 seed。

是否支持私有化部署？

企业版支持私有网络内部署与指定区域数据落地，需配置专属硬件资源，请通过商务渠道洽谈。