API HTTP

La API HTTP de Dropstone te da acceso programático a los mismos tres modelos que usa la CLI — Dropstone Fast, Pro y Heavy — a través de una interfaz compatible con OpenAI. Una clave, una factura, tres familias de modelos.

Usa la API cuando quieras llamar a Dropstone desde tu propio código: pipelines de CI, herramientas internas, automatización o aplicaciones de terceros. Para codificación interactiva, usa la CLI en su lugar.

URL base

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

Todos los endpoints están montados bajo /api/v1. La ruta está versionada para que los futuros cambios importantes aterricen en /api/v2 sin interrumpir tu código.

Autenticación

Cada solicitud debe incluir una clave de API en el encabezado Authorization:

Authorization: Bearer dsk_live_<tu-clave>

Generar una clave

1. Inicia sesión en dropstone.io/dashboard
2. Abre Configuración → API
3. Haz clic en Crear clave, dale un nombre (p. ej. CI de producción)
4. Copia la clave completa — solo la verás una vez

Las claves tienen el formato dsk_live_<43 caracteres>. Guárdalas en un gestor de secretos o en la variable de entorno DROPSTONE_API_KEY.

Revocar una clave

Revócala desde la misma página Configuración → API. La revocación es inmediata; las solicitudes en curso con la clave continúan, las nuevas reciben 401.

Créditos y facturación

La API es de pago por uso contra un saldo de créditos. No hay nivel gratuito ni suscripción en la superficie de la API.

• Compra créditos en dropstone.io/dashboard/billing. Stripe gestiona el pago.
• Cada solicitud deduce su costo de tu creditBalance.
• Cuando creditBalance baja a $0, la API devuelve 402 Créditos insuficientes hasta que recargues.
• Los créditos de suscripción (asignación mensual de Pro/Teams) y las cuotas de solicitudes gratuitas no se aplican a las solicitudes con clave de API.

Precios

El precio es el costo real de inferencia con un margen del 30% (1.3x). El costo total por solicitud se devuelve en el campo usage.cost de la respuesta, para que puedas verificar cada cargo.

Los tokens de prompt en caché se facturan a la tasa de caché del proveedor (típicamente ~5–10% de la tasa normal de entrada), por lo que las conversaciones de múltiples turnos se vuelven progresivamente más baratas.

Modelos

GET /api/v1/models

Lista los tres niveles disponibles.

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

Respuesta:

{
  "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 con OpenAI. Si has usado cualquier API compatible con OpenAI, esto se ve idéntico.

Cuerpo de la solicitud

Ejemplo: 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": "Escribe un haiku sobre depurar código."}
    ]
  }'

Respuesta

{
  "id": "gen-1779530142-EfBhlhO1U2frV6tvMgKV",
  "object": "chat.completion",
  "created": 1779530142,
  "model": "dropstone-fast",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Stack trace a medianoche..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 23,
    "total_tokens": 34,
    "cost": 0.0000098
  }
}

El campo usage.cost es el monto facturado en USD — lo que se dedujo de tu saldo de créditos por esta solicitud (costo real del proveedor × margen de 1.3).

Streaming

Establece "stream": true para obtener un flujo de Server-Sent Events con fragmentos de tokens. El flujo termina con una línea data: [DONE] y un fragmento final que contiene el bloque completo de 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": "Cuenta hasta 5."}]
  }'

Compatibilidad con el SDK de OpenAI

Como la superficie es compatible con OpenAI, puedes usar el SDK oficial de OpenAI sobrescribiendo 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": "Hola"}],
)
print(resp.choices[0].message.content)

Códigos de error

Forma de la respuesta 402

{
  "error": "Créditos insuficientes",
  "balance": 0,
  "message": "Tu saldo de créditos está vacío. Recarga en https://dropstone.io/dashboard/billing para continuar.",
  "topUpUrl": "https://dropstone.io/dashboard/billing"
}

Límites de tasa

No hay límites de tasa estrictos aplicados en la API hoy. Los niveles de uso por clave y los límites de gasto diario están planificados — cuando se lancen, tus claves existentes se clasificarán automáticamente según el gasto de por vida, similar al sistema de niveles de OpenAI.

Por ahora, establece presupuestos por clave tú mismo rastreando el campo usage.cost en tu aplicación.

Prácticas recomendadas

• Usa variables de entorno, nunca claves en línea: DROPSTONE_API_KEY=dsk_live_....
• Una clave por servicio, no una clave compartida en todas partes. Más fácil de revocar cuando un servicio se ve comprometido.
• Vigila usage.cost en las respuestas para rastrear el gasto en tiempo real.
• Maneja el 402 con elegancia — tu aplicación debe detectarlo y mostrar una llamada a la acción para recargar en lugar de reintentar.
• Almacena en caché las respuestas para solicitudes idénticas repetidas de tu lado — nosotros cacheamos a nivel de modelo, pero tú ahorras el margen completo al cortocircuitar antes de llegar a nosotros.

Diferencias con la CLI y el SDK

Si quieres acceso programático sin interfaz en CI o en un servidor, la API HTTP es la superficie correcta. El SDK es para incrustar el agente interactivo en un proceso de Node donde un humano sigue en el circuito.

Próximamente

Estas funciones están en la hoja de ruta y aterrizarán bajo el mismo espacio de nombres /api/v1:

• POST /api/v1/agent/run — endpoint de bucle de agente. Envía una tarea, obtén un diff terminado. Bucle de múltiples turnos del lado del servidor con herramientas integradas (edición de archivos, búsqueda web, ejecución de código). Precio fijo por tarea.
• POST /api/v1/memory/store + GET /api/v1/memory/query — memoria con estado a través de Qdrant. Contexto del agente que persiste entre llamadas.
• Inyección de herramientas MCP — incluye tus propias URL de servidor MCP en las solicitudes del agente, el agente las llama como herramientas nativas.
• Límites de gasto por clave — establece un límite diario en $ por clave desde el panel. Red de seguridad para CI.

Dale una estrella al repositorio de GitHub o sigue el registro de cambios para saber cuándo se lanzan.