Dropstone Docs

HTTP API

用于编程访问的公共 HTTP API。兼容 OpenAI 的聊天补全、按用量付费的积分、一个密钥适用于 Fast / Pro / Heavy。

Dropstone HTTP API 让您可以通过编程方式访问 CLI 所使用的同三个模型 — Dropstone Fast、Pro 和 Heavy — 接口与 OpenAI 兼容。一个密钥、一张账单、三个模型系列。

当您想从自己的代码中调用 Dropstone 时使用 API：CI 流水线、内部工具、自动化或第三方应用。对于交互式编码，请改用 CLI。

状态:

公共 API 目前处于预览阶段。端点结构已稳定，但定价和速率限制在正式发布前可能会有所调整。请固定您所依赖的接口。

基础 URL

https://api.dropstone.io/api/v1

所有端点都挂载在 /api/v1 下。路径带有版本号，因此未来的破坏性变更将落在 /api/v2 下，不会影响您的代码。

身份验证

每个请求都必须在 Authorization 头中包含 API 密钥：

Authorization: Bearer dsk_live_<your-key>

生成密钥

  1. 登录 dropstone.io/dashboard
  2. 打开 设置 → API
  3. 点击 创建密钥，为其命名（例如 Production CI）
  4. 复制完整密钥 — 您只会看到一次

密钥格式为 dsk_live_<43 个字符>。请将其存储在密钥管理器中，或放在 DROPSTONE_API_KEY 环境变量中。

撤销密钥

在同一个 设置 → API 页面中撤销。撤销立即生效；使用该密钥的在途请求会继续，新请求将返回 401。

安全:

请像对待密码一样对待您的 API 密钥。切勿将其提交到 git，切勿在聊天或截图中粘贴，切勿嵌入到前端代码包中。如果密钥泄露，请立即撤销并创建新密钥。

积分与计费

API 采用按用量付费，从积分余额中扣除的模式。API 没有免费套餐，也没有订阅。

  • 在 dropstone.io/dashboard/billing 购买积分。结账由 Stripe 处理。
  • 每个请求都会从您的 creditBalance 中扣除相应费用。
  • 当 creditBalance 降至 $0 时，API 将返回 402 积分不足，直到您充值。
  • 订阅积分（Pro/Teams 月度配额）和免费请求额度不适用于 API 密钥请求。

定价

定价是真实的推理成本，并附加 30% 的加价（1.3x）。每个请求的完整费用会通过响应中的 usage.cost 字段返回，因此您可以核对每一笔费用。

层级约 $/百万输入约 $/百万输出
dropstone-fast$0.35$1.43
dropstone-pro$0.72$2.86
dropstone-heavy$0.78$3.25

缓存的提示词令牌按提供商的缓存费率计费（通常约为正常输入费率的 5–10%），因此多轮对话会逐渐变得更便宜。

模型

GET /api/v1/models

列出三个可用层级。

curl https://api.dropstone.io/api/v1/models \
  -H "Authorization: Bearer $DROPSTONE_API_KEY"

响应：

{
  "object": "list",
  "data": [
    { "id": "dropstone-fast",  "object": "model", "display_name": "Dropstone Fast",  "owned_by": "dropstone" },
    { "id": "dropstone-pro",   "object": "model", "display_name": "Dropstone Pro",   "owned_by": "dropstone" },
    { "id": "dropstone-heavy", "object": "model", "display_name": "Dropstone Heavy", "owned_by": "dropstone" }
  ]
}

聊天补全

POST /api/v1/chat/completions

兼容 OpenAI 的聊天补全。如果您使用过任何兼容 OpenAI 的 API，这个接口看起来完全相同。

请求体

| 字段 | 类型 | 必填 | 描述 | |---|---|---| | model | string | 是 | 三个之一：dropstone-fast、dropstone-pro、dropstone-heavy | | messages | array | 是 | 包含 role 和 content 的消息对象列表 | | stream | boolean | 否 | 当为 true 时，返回服务器发送事件。默认为 false | | temperature | number | 否 | 采样温度，0..2。默认值因模型而异 | | max_tokens | number | 否 | 输出令牌的上限 | | tools | array | 否 | 函数调用工具模式，OpenAI 格式 | | tool_choice | string \| object | 否 | "auto"、"none" 或特定工具 |

示例：简单聊天

curl https://api.dropstone.io/api/v1/chat/completions \
  -H "Authorization: Bearer $DROPSTONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dropstone-fast",
    "messages": [
      {"role": "user", "content": "Write a haiku about debugging."}
    ]
  }'

响应

{
  "id": "gen-1779530142-EfBhlhO1U2frV6tvMgKV",
  "object": "chat.completion",
  "created": 1779530142,
  "model": "dropstone-fast",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Stack trace at midnight..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 23,
    "total_tokens": 34,
    "cost": 0.0000098
  }
}

usage.cost 字段是以美元计价的计费金额 — 即从您的积分余额中扣除的本次请求费用（实际提供商成本 × 1.3 加价）。

流式传输

设置 "stream": true 以获取令牌块的服务器发送事件流。流以 data: [DONE] 行和包含完整 usage 块的最终块结束。

curl https://api.dropstone.io/api/v1/chat/completions \
  -H "Authorization: Bearer $DROPSTONE_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "dropstone-fast",
    "stream": true,
    "messages": [{"role": "user", "content": "Count to 5."}]
  }'

OpenAI SDK 兼容性

由于接口与 OpenAI 兼容，您可以通过覆盖 base_url 来使用官方的 OpenAI SDK：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.dropstone.io/api/v1",
    api_key=os.environ["DROPSTONE_API_KEY"],
)

resp = client.chat.completions.create(
    model="dropstone-fast",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

错误代码

代码含义操作
400请求体无效（model 错误、缺少 messages 等）检查响应中的 error.message
401API 密钥缺失、格式错误或已撤销在仪表板中生成新密钥
402积分不足。 余额为 $0 或负数在 /dashboard/billing 充值
403账户已被暂停或封禁联系支持
429速率限制（未来 — 目前未强制执行）退避并重试
500服务器错误使用指数退避重试
502上游提供商错误使用指数退避重试

402 响应格式

{
  "error": "Insufficient credits",
  "balance": 0,
  "message": "Your credit balance is empty. Top up at https://dropstone.io/dashboard/billing to continue.",
  "topUpUrl": "https://dropstone.io/dashboard/billing"
}

速率限制

目前 API 没有强制执行硬性速率限制。按密钥的使用层级和每日消费上限已在规划中 — 当它们上线时，您现有的密钥将根据累计消费自动分层，类似于 OpenAI 的层级系统。

目前，请通过跟踪应用中的 usage.cost 字段自行设置每个密钥的预算。

推荐实践

  • 使用环境变量，切勿内联密钥：DROPSTONE_API_KEY=dsk_live_...。
  • 每个服务一个密钥，而不是一个密钥到处共享。当某个服务被攻破时更容易撤销。
  • 关注响应中的 usage.cost，实时跟踪消费。
  • 优雅处理 402 — 您的应用应检测到该错误并显示充值提示，而不是重试。
  • 在您这边缓存重复的相同请求 — 我们在模型层面进行缓存，但您在到达我们之前短路请求可以节省全部加价。

与 CLI 和 SDK 的差异

| 接口 | 身份验证 | 定价模式 | 模型 | 使用场景 | |---|---|---|---| | HTTP API（本页） | API 密钥 | 从积分余额按用量付费 | Fast / Pro / Heavy | CI、自动化、集成 | | CLI（文档） | 交互式登录 | 订阅 + 积分余额 | 同三个 + 免费开源模型 | 终端中的日常编码 | | JS SDK（文档） | 启动本地 CLI，继承其身份验证 | 与 CLI 相同 | 与 CLI 相同 | 在 Node 应用中嵌入代理 |

如果您需要在 CI 或服务器中进行无头编程访问，HTTP API 是正确的接口。SDK 用于在仍有人员参与的 Node 进程中嵌入交互式代理。

即将推出

以下功能已在路线图上，将落在相同的 /api/v1 命名空间下：

  • POST /api/v1/agent/run — 代理循环端点。发送任务，获得完成的差异。服务端多轮循环，内置工具（文件编辑、网络搜索、代码执行）。按任务统一计价。
  • POST /api/v1/memory/store + GET /api/v1/memory/query — 通过 Qdrant 实现有状态记忆。跨调用持久化的代理上下文。
  • MCP 工具注入 — 在代理请求中包含您自己的 MCP 服务器 URL，代理将其作为原生工具调用。
  • 按密钥消费上限 — 从仪表板为每个密钥设置每日 $ 限额。CI 安全网。

给 GitHub 仓库 加星或关注更新日志以了解它们何时上线。

Ctrl+I