API HTTP

L'API HTTP di Dropstone ti offre accesso programmatico agli stessi tre modelli usati dalla CLI — Dropstone Fast, Pro e Heavy — tramite un'interfaccia compatibile con OpenAI. Una chiave, una fattura, tre famiglie di modelli.

Usa l'API quando vuoi chiamare Dropstone dal tuo codice: pipeline CI, strumenti interni, automazione o app di terze parti. Per la codifica interattiva, usa invece la CLI.

URL di base

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

Tutti gli endpoint sono montati sotto /api/v1. Il percorso è versionato, quindi le future modifiche sostanziali arriveranno sotto /api/v2 senza interrompere il tuo codice.

Autenticazione

Ogni richiesta deve includere una chiave API nell'header Authorization:

Authorization: Bearer dsk_live_<your-key>

Generare una chiave

1. Accedi a dropstone.io/dashboard
2. Apri Impostazioni → API
3. Clicca Crea chiave, assegnale un nome (es. Produzione CI)
4. Copia la chiave completa — la vedrai solo una volta

Le chiavi hanno questo formato: dsk_live_<43 caratteri>. Conservale in un gestore di segreti o nella variabile d'ambiente DROPSTONE_API_KEY.

Revocare una chiave

Revoca dalla stessa pagina Impostazioni → API. La revoca è immediata; le richieste in corso con quella chiave continuano, le nuove ricevono 401.

Crediti e fatturazione

L'API è a consumo contro un saldo crediti. Non esiste un livello gratuito né un abbonamento sulla superficie API.

• Acquista crediti su dropstone.io/dashboard/billing. Stripe gestisce il pagamento.
• Ogni richiesta detrae il suo costo dal tuo creditBalance.
• Quando creditBalance scende a $0, l'API restituisce 402 Crediti insufficienti finché non ricarichi.
• I crediti dell'abbonamento (quota mensile Pro/Teams) e le quote di richieste gratuite non si applicano alle richieste con chiave API.

Prezzi

I prezzi sono il costo reale di inferenza applicato con un margine del 30% (1.3x). Il costo completo per richiesta viene restituito nel campo usage.cost della risposta, così puoi verificare ogni addebito.

I token di prompt memorizzati nella cache vengono fatturati alla tariffa cache del provider (in genere ~5–10% della tariffa input normale), quindi le conversazioni multi-turno diventano progressivamente più economiche.

Modelli

GET /api/v1/models

Elenca i tre livelli disponibili.

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

Risposta:

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

Completamenti chat

POST /api/v1/chat/completions

Completamenti chat compatibili con OpenAI. Se hai già usato un'API compatibile con OpenAI, questa ti sembrerà identica.

Corpo della richiesta

| Campo | Tipo | Obbligatorio | Descrizione | |---|---|---| | model | string | sì | Uno tra dropstone-fast, dropstone-pro, dropstone-heavy | | messages | array | sì | Elenco di oggetti messaggio con role e content | | stream | boolean | no | Quando true, restituisce Server-Sent Events. Predefinito false | | temperature | number | no | Temperatura di campionamento, 0..2. Predefinita specifica del modello | | max_tokens | number | no | Limite massimo di token di output | | tools | array | no | Schemi di strumenti per function calling, formato OpenAI | | tool_choice | string \| object | no | "auto", "none" o uno strumento specifico |

Esempio: chat semplice

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

Risposta

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

Il campo usage.cost è l'importo addebitato in USD — ciò che è stato detratto dal tuo saldo crediti per questa richiesta (costo reale del provider × margine 1.3).

Streaming

Imposta "stream": true per ottenere uno stream Server-Sent Events di chunk di token. Lo stream termina con una riga data: [DONE] e un chunk finale contenente il blocco usage completo.

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

Compatibilità con l'SDK OpenAI

Poiché la superficie è compatibile con OpenAI, puoi usare l'SDK OpenAI ufficiale sovrascrivendo base_url:

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)

Codici di errore

Forma della risposta 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"
}

Limiti di frequenza

Oggi non ci sono limiti di frequenza rigidi applicati sull'API. Sono previsti livelli di utilizzo per chiave e limiti di spesa giornalieri — quando verranno rilasciati, le tue chiavi esistenti verranno classificate automaticamente in base alla spesa complessiva, in modo simile al sistema a livelli di OpenAI.

Per ora, imposta tu i budget per chiave monitorando il campo usage.cost nella tua applicazione.

Pratiche consigliate

• Usa variabili d'ambiente, mai chiavi inline: DROPSTONE_API_KEY=dsk_live_....
• Una chiave per servizio, non una chiave condivisa ovunque. Più facile da revocare quando un servizio viene compromesso.
• Controlla usage.cost nelle risposte per monitorare la spesa in tempo reale.
• Gestisci il 402 con eleganza — la tua app dovrebbe rilevarlo e mostrare un invito a ricaricare invece di riprovare.
• Memorizza nella cache le risposte per richieste identiche ripetute lato tuo — noi facciamo cache a livello di modello, ma tu risparmi l'intero margine interrompendo la richiesta prima di raggiungerci.

Differenze rispetto a CLI e SDK

| Superficie | Autenticazione | Modello di prezzo | Modelli | Caso d'uso | |---|---|---|---| | API HTTP (questa pagina) | Chiave API | A consumo dal saldo crediti | Fast / Pro / Heavy | CI, automazione, integrazioni | | CLI (docs) | Accesso interattivo | Abbonamento + saldo crediti | Stessi tre + modelli open-source gratuiti | Codifica quotidiana in un terminale | | SDK JS (docs) | Avvia la CLI locale, ne eredita l'autenticazione | Come la CLI | Come la CLI | Incorporare l'agente in un'app Node |

Se vuoi accesso programmatico headless in CI o su un server, l'API HTTP è la superficie giusta. L'SDK serve per incorporare l'agente interattivo in un processo Node dove c'è ancora un umano nel ciclo.

In arrivo

Queste funzionalità sono nella roadmap e arriveranno sotto lo stesso namespace /api/v1:

• POST /api/v1/agent/run — endpoint del ciclo agente. Invia un compito, ottieni un diff finito. Ciclo multi-turno lato server con strumenti integrati (modifica file, ricerca web, esecuzione codice). Prezzo fisso per compito.
• POST /api/v1/memory/store + GET /api/v1/memory/query — memoria stateful tramite Qdrant. Contesto dell'agente che persiste tra le chiamate.
• Iniezione di strumenti MCP — includi i tuoi URL di server MCP nelle richieste dell'agente, l'agente li chiama come strumenti nativi.
• Limiti di spesa per chiave — imposta un limite giornaliero in $ per chiave dalla dashboard. Rete di sicurezza per CI.

Metti una stella al repository GitHub o segui il changelog per sapere quando verranno rilasciate.