HTTP API

Dropstone HTTP API は、CLI が使用するのと同じ3つのモデル — Dropstone Fast、Pro、Heavy — に、OpenAI互換のインターフェースでプログラムからアクセスできるようにします。1つのキー、1つの請求、3つのモデルファミリー。

独自のコードから Dropstone を呼び出したい場合（CIパイプライン、社内ツール、自動化、サードパーティ製アプリなど）は、API を使用してください。対話型コーディングには、代わりに CLI を使用してください。

ベース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 は クレジット残高に対する従量課金 です。API サーフェスには無料枠もサブスクリプションもありません。

• クレジットは dropstone.io/dashboard/billing で購入できます。チェックアウトは Stripe が処理します。
• 各リクエストは、そのコストを creditBalance から差し引きます。
• creditBalance が $0 になると、チャージするまで API は 402 Insufficient credits を返します。
• サブスクリプションのクレジット（Pro/Teams の月間許容量）と無料リクエストの割り当ては、API キーのリクエストには 適用されません。

価格

価格は実際の推論コストに 30% のマークアップ（1.3x）を加えたものです。リクエストごとの全コストはレスポンスの usage.cost フィールドで返されるため、すべての請求を検証できます。

キャッシュされたプロンプトトークンは、プロバイダーのキャッシュレート（通常、通常の入力レートの約5〜10%）で請求されるため、マルチターンの会話は徐々に安くなります。

モデル

GET /api/v1/models

利用可能な3つのティアを一覧表示します。

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 | いいえ | 出力トークンの上限 | | 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 フィールドは USD での請求額 です — このリクエストでクレジット残高から差し引かれた金額（実際のプロバイダーコスト × 1.3 マークアップ）。

ストリーミング

"stream": true を設定すると、トークンチャンクの 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)

エラーコード

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_...。
• サービスごとに1つのキー — 1つのキーをどこでも共有しないでください。サービスが侵害されたときに失効が容易になります。
• レスポンスの usage.cost を監視 — 支出をリアルタイムで追跡します。
• 402 を適切に処理 — アプリは 402 を検出し、再試行する代わりにチャージの CTA を表示する必要があります。
• 同一のリクエストのレスポンスをキャッシュ — モデルレベルでキャッシュしていますが、当社に到達する前にショートサーキットすることで、マークアップ全体を節約できます。

CLI および SDK との違い

CI やサーバーでヘッドレスなプログラムアクセスが必要な場合は、HTTP API が適切なサーフェスです。SDK は、人間がループに参加している Node プロセスに対話型エージェントを埋め込むためのものです。

近日公開

これらはロードマップにあり、同じ /api/v1 名前空間の下に配置されます：

• POST /api/v1/agent/run — エージェントループエンドポイント。タスクを送信すると、完成した diff が返されます。組み込みツール（ファイル編集、ウェブ検索、コード実行）を備えたサーバーサイドのマルチターンループ。タスクごとのフラットな価格設定。
• POST /api/v1/memory/store + GET /api/v1/memory/query — Qdrant によるステートフルメモリ。呼び出しをまたいで持続するエージェントコンテキスト。
• MCP ツールインジェクション — エージェントリクエストに独自の MCP サーバー URL を含めると、エージェントがネイティブツールとして呼び出します。
• キーごとの支出上限 — ダッシュボードからキーごとに日次 $ 上限を設定。CI のセーフティネット。

GitHub リポジトリ にスターを付けるか、チェンジログ をウォッチして、リリース時期を確認してください。