TokenPostie 最终用户文档

AI Agent 接入

AI 摘要

AI Agent 应优先读取 /llms.txt，再按任务读取对应 Markdown 页面。生成代码时必须通过 GET /v1/models 发现模型，不能猜测模型名，不能要求用户把真实 API Key 粘贴进提示词、日志或代码仓库。

稳定入口

入口用途
/llms.txt给 LLM 的精简站点索引
/llms-full.txt给 LLM 的完整文档汇总
/docs/v1.mdv1 稳定公开能力入口
/docs/quickstart.md快速接入 Markdown 版
/docs/guides/sdk-examples.mdSDK 示例 Markdown 版
/docs/guides/account-and-kyc.md账号、租户、项目和实名说明
/docs/guides/customer-console.md客户控制台功能说明
/docs/api/models.md模型发现规则 Markdown 版
/docs/guides/billing-and-usage.md账单和用量说明
/docs/guides/invoices-and-payments.md发票与付款说明
/docs/guides/troubleshooting-and-security.md排障和安全建议
/docs/reference/errors.md错误码 Markdown 版
/console客户控制台，人类用户查看账号、实名、授权、请求日志、账单和发票信息
/console/api/agent-context客户登录态下的只读 Agent 上下文，返回脱敏 API Key 摘要、可用模型、文档入口和最近请求日志摘要

给 AI 编程助手的最小接入步骤

当用户要求你“帮我接入 TokenPostie API”时，请按下面顺序执行：

  1. 让用户确认 API Base URL：https://newapi.yxhhkj.com。
  2. 告诉用户在客户控制台创建或选择 API Key，但不要让用户把真实 Key 发给你。
  3. 在代码中读取服务端环境变量，例如 TOKENPOSTIE_API_KEY。
  4. 先生成 GET /v1/models 的模型发现代码。
  5. 从模型列表返回的 data[].id 中选择模型，不要硬编码文档里的占位模型名。
  6. 再生成 Chat、Embedding 或 Rerank 的调用代码。
  7. 给所有请求记录 TokenPostie 返回的 request id 或响应头中的请求标识，便于排查。
  8. 对错误处理只依赖 TokenPostie 的 error.code、HTTP 状态码和 Retry-After。
  9. 对费用说明只引用客户控制台账单、用量和余额流水，不自行估算最终扣费。

客户登录态 Agent 上下文

如果 AI Agent 与客户控制台运行在同一个受信任浏览器会话里，可以读取：

GET /console/api/agent-context

这个接口只用于读取上下文，不会创建 API Key、充值、调账或修改后台配置。返回内容包括：

  • 当前登录成员、当前组织、项目和权限摘要。
  • 当前组织下客户可见的 API Key 脱敏摘要，只包含 apiKeyId、displayName、tokenPreview、状态、限额和模型范围。
  • 当前客户可见且可商业调用的模型列表。
  • 快速开始、模型列表、API Key 与限额、计费、错误码和 llms.txt 文档入口。
  • 最近客户可见请求日志摘要，包括 request id、状态、HTTP 状态码、耗时和 usage，不包含用户输入正文、模型输出正文或上游原始错误日志。

安全边界：

  • 不返回完整 API Key。
  • 不返回供应商密钥。
  • 不返回上游原始日志。
  • 不返回用户输入正文。
  • 不返回模型输出正文。
  • 不返回平台管理后台数据。

AI Agent 拿到该上下文后，只能用它做模型发现、文档定位、错误码排查和请求日志定位。真实 API 调用仍应由客户自己的代码通过服务端环境变量读取完整 API Key。

Agent 规则

  1. 先调用 GET /v1/models，再选择模型。
  2. 不要把最终用户 API Key 写入提示词、日志、代码注释或持久化配置。
  3. 对错误处理只依赖 TokenPostie 返回的稳定 error.code。
  4. 对账单解释只引用 TokenPostie 的 usage 与账单结果，不自行估算最终扣费。
  5. 遇到 rate_limit_exceeded、insufficient_quota、model_access_denied 时，不要自动重试刷量，应提示客户处理配额、余额或授权。
  6. 当用户需要查看实际可见模型、近期请求、实名状态、账单或发票信息时，引导用户打开 /console，不要要求用户把 API Key 粘贴给 AI Agent。
  7. 如果可访问 /console/api/agent-context，优先使用该只读上下文定位模型、文档、请求日志和错误码；不要用它尝试写操作。

常见任务映射

用户目标先读页面生成内容
写第一段调用代码/docs/v1.md、/docs/quickstart.md、/docs/guides/sdk-examples.md、/docs/api/models.md环境变量读取、模型发现、Chat 请求
接 Anthropic Messages/docs/api/models.md、/docs/api/anthropic-messages.md模型发现、Messages 请求、首期纯文本限制
接 embedding/docs/api/models.md、/docs/api/embeddings.md模型发现、Embedding 请求、usage 处理
接 rerank/docs/api/models.md、/docs/api/rerank.md模型发现、Rerank 请求、复核提示
排查失败请求/docs/reference/errors.md、/docs/guides/troubleshooting-and-security.md错误码解释、request id 排查步骤
核对费用/docs/guides/billing-and-usage.md、/docs/guides/invoices-and-payments.md账单口径说明、对账材料清单

错误与费用处理边界

  • 401：提示用户检查服务端环境变量和 Authorization 头，不要让用户把真实 Key 发给你。
  • 403：提示检查实名、模型授权、项目权限或 API Key 权限。
  • 429：提示检查余额、授信、RPM、TPM、QPM，并按 Retry-After 降速。
  • 502/503：提示记录 request id，并到客户控制台请求日志查看摘要。
  • 费用核对：以客户控制台的账单、余额流水、已确认用量和发票记录为准。

推荐系统提示词片段

你正在通过 TokenPostie 调用模型。接入前必须读取 /llms.txt。
不要猜测模型名，必须调用 GET /v1/models 获取当前 API Key 可见模型。
API Key 只能放在 Authorization: Bearer 中，不得写入日志或提示词。
错误处理以 TokenPostie error.code 为准。
费用说明以客户控制台账单和余额流水为准，不自行估算最终扣费。