返回用户页面

Platform API

平台 API 使用说明

返回首页

Quick Start

快速开始

Example

最小请求示例

把下面命令中的 YOUR_HOST 和 YOUR_API_KEY 替换成你的平台地址和 API Key：

curl -X POST https://YOUR_HOST/api/v1/respond \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "请解释这段文本的核心观点。"
  }'

如果你要把多轮对话接在同一条会话里，后续请求继续传回上一次响应里的 conversation.id 即可：

{
  "conversationId": "conv_xxx",
  "prompt": "继续展开第二点。"
}

Response

响应里会返回什么

成功时，响应里会包含：

  • assistantMessage：本次回答内容和使用信息
  • data.markdown：后端整理好的 Markdown 展示文本，和网页端显示内容一致
  • data.structured_result：可编程使用的结构化结果；普通分支暂时可能为 null，结构化分支会返回 JSON 对象
  • data.workflow：本次后端工作流摘要，用于调试和排查
  • conversation：更新后的完整会话，可从中继续取 conversation.id
  • billing：本次计费后的摘要

平台的长期输出契约是：模型优先产出结构化 JSON，后端校验并转换为 Markdown；API 同时返回结构化结果和 Markdown，网页前端只显示 Markdown。其他分支 APP 会后续逐个迁移到这个契约。

最常见的失败情况：

  • 401：缺少 API Key 或 API Key 无效
  • 402：余额不足
  • 429：触发使用限制

Branch Apps

各个分支 APP 如何调用

所有分支 APP 复用同一个平台接口形态：POST /api/v1/respond。调用哪个分支，取决于你请求的分支域名或端口；服务端会按该分支的 WHWM_PLATFORM_APP_SLUG 加载对应提示词、案例、知识库和文案。

curl -X POST https://PHYSICS_HOST/api/v1/respond \
  -H "content-type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "请用 WHWM 方法分析这道物理题。"
  }'

响应中的 billing 会返回本次 API token 计费后的摘要；API 调用按 api_token_metered 记录。

平台内部会同时写两层账：provider_usage 记录 WHWM 对 OpenAI、Mathpix、Hugging Face、小模型、本地 faster-whisper 等供应商或本地模型的真实消耗，usage 记录平台记在用户头上的网页/API 用量。普通用户只能看到 usage 这一层。

Tools

平台小工具如何调用

小工具优先给网页前端使用，通常通过登录态 Cookie 调用。文件类工具先把文件缓存到本地，再把返回的 fileId 传给后续工具接口。

POST /api/cache-local-file
POST /api/local-file-converted-markdown
POST /api/local-file-transcription

/api/local-file-transcription 用于音频转文字记录，要求登录；成功后会把云端转写返回的 token usage 写入用户用量记录，并在响应中返回 billing。如果后台为了上传限制自动压缩或切分音频，接口仍按原始音频累计时间输出。

/api/local-file-converted-markdown 用于文档转 Markdown，要求登录；如果实际调用 Mathpix 或 Hugging Face token，平台会在后台写入独立的 provider_usage 记录，不混入普通对话 token 配额，也不返回给普通用户；缓存命中不会重复记录外部工具费用。

图形渲染类工具是平台能力，各分支提示词可以生成对应 JSON，由前端或后端调用统一渲染接口：

POST /api/diagrams/circuit
POST /api/diagrams/circuit-layout
POST /api/diagrams/mechanics
POST /api/diagrams/optics
POST /api/diagrams/matplotlib