API HTTP

L'API HTTP Dropstone vous donne un accès programmatique aux trois mêmes modèles que ceux utilisés par le CLI — Dropstone Fast, Pro et Heavy — via une interface compatible OpenAI. Une seule clé, une seule facture, trois familles de modèles.

Utilisez l'API lorsque vous souhaitez appeler Dropstone depuis votre propre code : pipelines CI, outils internes, automatisation ou applications tierces. Pour le codage interactif, utilisez plutôt le CLI.

URL de base

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

Tous les endpoints sont montés sous /api/v1. Le chemin est versionné afin que de futurs changements majeurs arrivent sous /api/v2 sans perturber votre code.

Authentification

Chaque requête doit inclure une clé API dans l'en-tête Authorization :

Authorization: Bearer dsk_live_<votre-clé>

Générer une clé

1. Connectez-vous à dropstone.io/dashboard
2. Ouvrez Settings → API
3. Cliquez sur Create key, donnez-lui un nom (par ex. Production CI)
4. Copiez la clé complète — vous ne la verrez qu'une seule fois

Les clés ressemblent à dsk_live_<43 caractères>. Stockez-les dans un gestionnaire de secrets ou dans la variable d'environnement DROPSTONE_API_KEY.

Révoquer une clé

Révoquez-la depuis la même page Settings → API. La révocation est immédiate ; les requêtes en cours avec la clé continuent, les nouvelles requêtes reçoivent un 401.

Crédits et facturation

L'API est à l'utilisation contre un solde de crédits. Il n'y a pas de niveau gratuit ni d'abonnement sur la surface API.

• Achetez des crédits sur dropstone.io/dashboard/billing. Stripe gère le paiement.
• Chaque requête déduit son coût de votre creditBalance.
• Lorsque creditBalance tombe à 0 $, l'API renvoie 402 Crédits insuffisants jusqu'à ce que vous rechargiez.
• Les crédits d'abonnement (allocation mensuelle Pro/Teams) et les quotas de requêtes gratuites ne s'appliquent pas aux requêtes avec clé API.

Tarifs

Les tarifs correspondent au coût réel d'inférence avec une majoration de 30 % (1,3x). Le coût complet par requête est renvoyé dans le champ usage.cost de la réponse, afin que vous puissiez vérifier chaque débit.

Les jetons de prompt en cache sont facturés au tarif de cache du fournisseur (généralement ~5 à 10 % du tarif d'entrée normal), de sorte que les conversations multi-tours deviennent progressivement moins chères.

Modèles

GET /api/v1/models

Liste les trois niveaux disponibles.

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

Réponse :

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

Completions de chat

POST /api/v1/chat/completions

Completions de chat compatibles OpenAI. Si vous avez déjà utilisé une API compatible OpenAI, cela vous semblera identique.

Corps de la requête

Exemple : chat simple

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

Réponse

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

Le champ usage.cost est le montant facturé en USD — ce qui a été déduit de votre solde de crédits pour cette requête (coût réel du fournisseur × majoration de 1,3).

Streaming

Définissez "stream": true pour obtenir un flux Server-Sent Events de morceaux de jetons. Le flux se termine par une ligne data: [DONE] et un dernier morceau contenant le bloc usage complet.

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é SDK OpenAI

Comme la surface est compatible OpenAI, vous pouvez utiliser le SDK OpenAI officiel en remplaçant 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)

Codes d'erreur

Forme de la réponse 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"
}

Limites de débit

Aucune limite de débit stricte n'est appliquée sur l'API aujourd'hui. Des niveaux d'utilisation par clé et des plafonds de dépense quotidiens sont prévus — lorsqu'ils seront disponibles, vos clés existantes seront automatiquement classées en fonction de la dépense cumulée, de manière similaire au système de niveaux d'OpenAI.

Pour l'instant, définissez vous-même des budgets par clé en suivant le champ usage.cost dans votre application.

Pratiques recommandées

• Utilisez des variables d'environnement, jamais de clés en dur : DROPSTONE_API_KEY=dsk_live_....
• Une clé par service, pas une clé partagée partout. Plus facile à révoquer lorsqu'un service est compromis.
• Surveillez usage.cost dans les réponses pour suivre les dépenses en temps réel.
• Gérez le 402 avec élégance — votre application doit le détecter et afficher un appel à l'action pour recharger plutôt que de réessayer.
• Mettez en cache les réponses pour les requêtes identiques répétées de votre côté — nous mettons en cache au niveau du modèle, mais vous économisez la majoration complète en court-circuitant avant de nous atteindre.

Différences avec le CLI et le SDK

Si vous souhaitez un accès programmatique sans interface dans un CI ou un serveur, l'API HTTP est la surface adaptée. Le SDK est destiné à intégrer l'agent interactif dans un processus Node où un humain reste dans la boucle.

À venir

Ces éléments sont sur la feuille de route et arriveront sous le même espace de noms /api/v1 :

• POST /api/v1/agent/run — endpoint de boucle d'agent. Envoyez une tâche, obtenez un diff terminé. Boucle multi-tours côté serveur avec outils intégrés (édition de fichiers, recherche web, exécution de code). Tarification forfaitaire par tâche.
• POST /api/v1/memory/store + GET /api/v1/memory/query — mémoire avec état via Qdrant. Contexte d'agent persistant entre les appels.
• Injection d'outils MCP — incluez vos propres URL de serveur MCP dans les requêtes d'agent, l'agent les appelle comme outils natifs.
• Plafonds de dépense par clé — définissez une limite quotidienne en $ par clé depuis le tableau de bord. Filet de sécurité pour le CI.

Mettez une étoile sur le dépôt GitHub ou suivez le journal des modifications pour savoir quand ils seront disponibles.