HTTP-API

Die Dropstone-HTTP-API gibt Ihnen programmatischen Zugriff auf dieselben drei Modelle, die auch die CLI verwendet — Dropstone Fast, Pro und Heavy — über eine OpenAI-kompatible Schnittstelle. Ein Schlüssel, eine Rechnung, drei Modellfamilien.

Nutzen Sie die API, wenn Sie Dropstone aus Ihrem eigenen Code aufrufen möchten: CI-Pipelines, interne Tools, Automatisierung oder Drittanbieter-Apps. Für interaktives Programmieren verwenden Sie stattdessen die CLI.

Basis-URL

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

Alle Endpunkte sind unter /api/v1 montiert. Der Pfad ist versioniert, sodass zukünftige bahnbrechende Änderungen unter /api/v2 landen, ohne Ihren Code zu stören.

Authentifizierung

Jede Anfrage muss einen API-Schlüssel im Authorization-Header enthalten:

Authorization: Bearer dsk_live_<your-key>

Einen Schlüssel erstellen

1. Melden Sie sich bei dropstone.io/dashboard an
2. Öffnen Sie Einstellungen → API
3. Klicken Sie auf Schlüssel erstellen, geben Sie ihm einen Namen (z. B. Production CI)
4. Kopieren Sie den vollständigen Schlüssel — Sie sehen ihn nur einmal

Schlüssel sehen aus wie dsk_live_<43 Zeichen>. Speichern Sie sie in einem Secrets-Manager oder in der Umgebungsvariable DROPSTONE_API_KEY.

Einen Schlüssel widerrufen

Widerrufen Sie ihn auf derselben Seite Einstellungen → API. Der Widerruf ist sofort wirksam; laufende Anfragen mit dem Schlüssel werden fortgesetzt, neue Anfragen erhalten 401.

Guthaben & Abrechnung

Die API ist Pay-per-Use gegen ein Guthaben. Es gibt keinen kostenlosen Tarif und kein Abonnement auf der API-Oberfläche.

• Kaufen Sie Guthaben unter dropstone.io/dashboard/billing. Stripe übernimmt den Checkout.
• Jede Anfrage zieht ihre Kosten von Ihrem creditBalance ab.
• Wenn creditBalance auf $0 fällt, gibt die API 402 Unzureichendes Guthaben zurück, bis Sie aufladen.
• Abonnement-Guthaben (monatliche Pro/Teams-Zulage) und kostenlose Anfragekontingente gelten nicht für API-Schlüssel-Anfragen.

Preise

Die Preise sind die tatsächlichen Inferenzkosten, die mit einem Aufschlag von 30 % (1.3x) durchgereicht werden. Die vollständigen Kosten pro Anfrage werden im Feld usage.cost der Antwort zurückgegeben, sodass Sie jede Belastung überprüfen können.

Gecachte Prompt-Tokens werden zum Cache-Satz des Anbieters abgerechnet (typischerweise ~5–10 % des normalen Eingabesatzes), sodass mehrteilige Konversationen zunehmend günstiger werden.

Modelle

GET /api/v1/models

Listet die drei verfügbaren Stufen auf.

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

Antwort:

{
  "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" }
  ]
}

Chat-Completions

POST /api/v1/chat/completions

OpenAI-kompatible Chat-Completions. Wenn Sie bereits eine OpenAI-kompatible API verwendet haben, sieht das identisch aus.

Anforderungstext

| Feld | Typ | Erforderlich | Beschreibung | |---|---|---| | model | string | ja | Eines von dropstone-fast, dropstone-pro, dropstone-heavy | | messages | array | ja | Liste von Nachrichtenobjekten mit role und content | | stream | boolean | nein | Wenn true, werden Server-Sent Events zurückgegeben. Standard false | | temperature | number | nein | Sampling-Temperatur, 0..2. Standard modellspezifisch | | max_tokens | number | nein | Obergrenze für Ausgabe-Tokens | | tools | array | nein | Tool-Schemas für Funktionsaufrufe, OpenAI-Format | | tool_choice | string \| object | nein | "auto", "none" oder ein bestimmtes Tool |

Beispiel: einfacher Chat

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."}
    ]
  }'

Antwort

{
  "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
  }
}

Das Feld usage.cost ist der abgerechnete Betrag in USD — was für diese Anfrage von Ihrem Guthaben abgezogen wurde (tatsächliche Anbieterkosten × 1.3 Aufschlag).

Streaming

Setzen Sie "stream": true, um einen Server-Sent-Events-Stream von Token-Blöcken zu erhalten. Der Stream endet mit einer data: [DONE]-Zeile und einem letzten Block, der den vollständigen usage-Block enthält.

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-Kompatibilität

Da die Oberfläche OpenAI-kompatibel ist, können Sie das offizielle OpenAI-SDK verwenden, indem Sie base_url überschreiben:

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)

Fehlercodes

Form der 402-Antwort

{
  "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"
}

Rate-Limits

Es gibt heute keine harten Rate-Limits auf der API. Nutzungsstufen pro Schlüssel und tägliche Ausgabenobergrenzen sind geplant — wenn sie eingeführt werden, werden Ihre vorhandenen Schlüssel automatisch basierend auf den Gesamtausgaben eingestuft, ähnlich dem Stufensystem von OpenAI.

Legen Sie vorerst selbst Budgets pro Schlüssel fest, indem Sie das Feld usage.cost in Ihrer Anwendung verfolgen.

Empfohlene Vorgehensweisen

• Verwenden Sie Umgebungsvariablen, niemals Inline-Schlüssel: DROPSTONE_API_KEY=dsk_live_....
• Ein Schlüssel pro Dienst, nicht ein Schlüssel überall geteilt. Einfacher zu widerrufen, wenn ein Dienst kompromittiert ist.
• Beobachten Sie usage.cost in Antworten, um Ausgaben in Echtzeit zu verfolgen.
• Behandeln Sie 402 elegant — Ihre App sollte dies erkennen und einen Auflade-CTA anzeigen, anstatt erneut zu versuchen.
• Cachen Sie Antworten für wiederholte identische Anfragen auf Ihrer Seite — wir cachen auf Modellebene, aber Sie sparen den vollständigen Aufschlag, indem Sie vor uns kurzschließen.

Unterschiede zur CLI und zum SDK

| Oberfläche | Authentifizierung | Preismodell | Modelle | Anwendungsfall | |---|---|---|---| | HTTP-API (diese Seite) | API-Schlüssel | Pay-per-Use vom Guthaben | Fast / Pro / Heavy | CI, Automatisierung, Integrationen | | CLI (Dokumentation) | Interaktive Anmeldung | Abonnement + Guthaben | Dieselben drei + kostenlose Open-Source-Modelle | Tägliches Programmieren im Terminal | | JS-SDK (Dokumentation) | Startet lokale CLI, erbt deren Authentifizierung | Wie CLI | Wie CLI | Einbettung des Agents in eine Node-App |

Wenn Sie headless programmatischen Zugriff in CI oder auf einem Server wünschen, ist die HTTP-API die richtige Oberfläche. Das SDK dient zum Einbetten des interaktiven Agents in einen Node-Prozess, bei dem ein Mensch weiterhin im Loop ist.

In Kürze verfügbar

Diese Punkte stehen auf der Roadmap und werden unter demselben /api/v1-Namespace landen:

• POST /api/v1/agent/run — Agent-Loop-Endpunkt. Senden Sie eine Aufgabe, erhalten Sie einen fertigen Diff. Serverseitiger mehrteiliger Loop mit integrierten Tools (Dateibearbeitung, Websuche, Codeausführung). Feste Preise pro Aufgabe.
• POST /api/v1/memory/store + GET /api/v1/memory/query — zustandsbehafteter Speicher über Qdrant. Agent-Kontext, der über Aufrufe hinweg bestehen bleibt.
• MCP-Tool-Injektion — fügen Sie Ihre eigenen MCP-Server-URLs in Agent-Anfragen ein, der Agent ruft sie als native Tools auf.
• Ausgabenobergrenzen pro Schlüssel — legen Sie ein tägliches $-Limit pro Schlüssel im Dashboard fest. CI-Sicherheitsnetz.

Sternen Sie das GitHub-Repository oder verfolgen Sie das Changelog, um zu erfahren, wann sie verfügbar sind.