#核心概念

理解以下概念，有助于控制成本、避免超长报错，并正确对接 HTTP API 与 OpenAI SDK。

#Token 与 usage

Token 是模型处理文本的基本单位，可粗略理解为「字 / 词」的切分片段。不同模型分词方式不同，中文、英文、数字、符号 的 token 数未必与字符数 1:1 对应。

每次成功的 Chat Completions 响应（非流式）通常包含 usage 字段，例如：

"usage": {
  "prompt_tokens": 100,
  "completion_tokens": 200,
  "total_tokens": 300
}

• prompt_tokens：输入侧（含 messages 与部分系统开销）
• completion_tokens：模型生成内容
• 控制台 使用记录 与 费用账单 按平台计价规则据此扣费

流式调用结束后，也可能在最后一个 chunk 或汇总接口中提供 usage，以实际返回为准。

#上下文窗口

上下文窗口 指单次请求中，模型能处理的 最大 token 总量（通常包括用户输入、历史多轮、模型输出；部分推理模型还包含中间推理 token）。

若对话过长：

1. 超出部分可能被截断，导致模型「忘记」 earlier 内容
2. 可能直接返回参数或长度类错误

建议：

• 在 模型广场  查看各模型上下文上限
• 长文档场景优先选用 长上下文 模型，或做分段摘要 + RAG
• 多模态输入（图片、音频等）常有 更严格的输入限制，以模型说明为准

#模型 ID

模型 ID 是 API 中 model 字段的字符串，是调用时的唯一标识。

• 必须从 控制台模型广场 复制，勿臆造或沿用其他平台的名称
• API Key 可配置 可用模型 子集；请求未授权的 ID 会失败
• 厂商升级版本时 ID 可能变化（如 glm-5 → glm-5.1），需关注控制台公告

详见 工具接入概览 与控制台 模型广场。

#API Key 与控制台登录

• API Key：用于 Authorization: Bearer，调用 网关 API
• 控制台 JWT / Session：仅用于登录 console.haiyushuke.com 管理资源

二者不可混用。Key 泄露风险高，须 妥善保管。

#余额与扣费

调用前账户需有足够 余额（预付费模式）。扣费一般发生在请求成功并完成计量之后；余额不足时返回 402 / INSUFFICIENT_BALANCE。见 计费与财务。

#统一网关

海宇数科 统一网关 对上游多厂商做路由与计量：您面对的是一个 Base URL 与一套 Key 体系，底层模型由平台调度至对应供应商。因此文档与控制台以 海宇模型 ID 为准，而非各厂商原站产品名。

#延伸阅读

• 快速开始
• 常见问题