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. 開啟 Settings → API
  3. 點擊 Create key，為它命名（例如 Production CI）
  4. 複製完整的金鑰 — 你只會看到它一次

金鑰的格式為 dsk_live_<43 chars>。請將它們存放在密碼管理工具或 DROPSTONE_API_KEY 環境變數中。

撤銷金鑰

從同一個 Settings → API 頁面撤銷。撤銷會立即生效；使用該金鑰的進行中請求會繼續，新請求則會收到 401。

安全性:

請將 API 金鑰視為密碼。絕對不要提交到 git、貼在聊天或截圖中，也不要嵌入前端 bundle。如果金鑰外洩，請立即撤銷並建立新的金鑰。

點數與計費

API 採用按用量付費，從點數餘額扣款。API 介面沒有免費方案，也沒有訂閱制。

  • 在 dropstone.io/dashboard/billing 購買點數。結帳由 Stripe 處理。
  • 每個請求會從你的 creditBalance 扣除對應費用。
  • 當 creditBalance 降到 $0 時，API 會回傳 402 Insufficient credits，直到你儲值為止。
  • 訂閱點數（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

快取的提示詞 token 會以供應商的快取費率計費（通常約為一般輸入費率的 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 時，回傳 Server-Sent Events。預設 false | | temperature | number | 否 | 取樣溫度，0..2。預設依模型而定 | | max_tokens | number | 否 | 輸出 token 的上限 | | tools | array | 否 | 函式呼叫的工具 schema，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 即可取得 token 區塊的 Server-Sent Events 串流。串流會以 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 — 你的應用程式應偵測此錯誤並顯示儲值 CTA，而不是重試。
  • 快取重複的相同請求 — 我們會在模型層級快取，但如果你在到達我們之前就短路，可以省下完整的加成費用。

與 CLI 和 SDK 的差異

| 介面 | 驗證 | 定價模式 | 模型 | 使用情境 | |---|---|---|---| | HTTP API（本頁） | API 金鑰 | 從點數餘額按用量付費 | Fast / Pro / Heavy | CI、自動化、整合 | | CLI（文件） | 互動式登入 | 訂閱 + 點數餘額 | 相同三個 + 免費開源模型 | 在終端機中進行日常編寫程式碼 | | JS SDK（文件） | 啟動本機 CLI，繼承其驗證 | 與 CLI 相同 | 與 CLI 相同 | 在 Node 應用程式中嵌入 agent |

如果你需要在 CI 或伺服器中進行無頭式程式化存取，HTTP API 是正確的介面。SDK 則用於在仍有真人參與的 Node 程序中嵌入互動式 agent。

即將推出

以下功能已在藍圖上，並會落在相同的 /api/v1 命名空間下：

  • POST /api/v1/agent/run — agent 迴圈端點。傳送任務，取得完成的 diff。伺服器端多輪迴圈，內建工具（檔案編輯、網頁搜尋、程式碼執行）。每個任務固定計價。
  • POST /api/v1/memory/store + GET /api/v1/memory/query — 透過 Qdrant 的有狀態記憶。跨呼叫持續存在的 agent 上下文。
  • MCP 工具注入 — 在 agent 請求中包含你自己的 MCP 伺服器 URL，agent 會將它們視為原生工具呼叫。
  • 每個金鑰的消費上限 — 從儀表板為每個金鑰設定每日 $ 上限。CI 安全網。

在 GitHub repo 上按星號，或追蹤 changelog，即可得知這些功能何時推出。

Ctrl+I