API HTTP

A API HTTP do Dropstone oferece acesso programático aos mesmos três modelos que a CLI usa — Dropstone Fast, Pro e Heavy — por meio de uma interface compatível com OpenAI. Uma chave, uma fatura, três famílias de modelos.

Use a API quando quiser chamar o Dropstone a partir do seu próprio código: pipelines de CI, ferramentas internas, automação ou aplicativos de terceiros. Para codificação interativa, use a CLI.

URL base

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

Todos os endpoints estão montados sob /api/v1. O caminho é versionado, então futuras mudanças que quebrem compatibilidade serão lançadas sob /api/v2 sem interromper seu código.

Autenticação

Toda requisição deve incluir uma chave de API no cabeçalho Authorization:

Authorization: Bearer dsk_live_<sua-chave>

Gerar uma chave

1. Entre em dropstone.io/dashboard
2. Abra Configurações → API
3. Clique em Criar chave, dê um nome (ex.: CI de produção)
4. Copie a chave completa — você só a verá uma vez

As chaves têm o formato dsk_live_<43 caracteres>. Armazene-as em um gerenciador de segredos ou na variável de ambiente DROPSTONE_API_KEY.

Revogar uma chave

Revogue na mesma página Configurações → API. A revogação é imediata; requisições em andamento com a chave continuam, novas requisições recebem 401.

Créditos e cobrança

A API é pré-paga contra um saldo de créditos. Não há camada gratuita nem assinatura na superfície da API.

• Compre créditos em dropstone.io/dashboard/billing. O Stripe cuida do checkout.
• Cada requisição deduz seu custo do seu creditBalance.
• Quando o creditBalance chega a $0, a API retorna 402 Créditos insuficientes até você recarregar.
• Créditos de assinatura (franquia mensal Pro/Teams) e cotas de requisições gratuitas não se aplicam a requisições com chave de API.

Preços

O preço é o custo real de inferência repassado com um acréscimo de 30% (1.3x). O custo total por requisição é retornado no campo usage.cost da resposta, para que você possa verificar cada cobrança.

Tokens de prompt em cache são cobrados pela taxa de cache do provedor (tipicamente ~5–10% da taxa normal de entrada), então conversas de múltiplas etapas ficam progressivamente mais baratas.

Modelos

GET /api/v1/models

Lista as três camadas disponíveis.

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

Resposta:

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

Chat completions compatível com OpenAI. Se você já usou qualquer API compatível com OpenAI, isso parece idêntico.

Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição | |---|---|---| | model | string | sim | Um de dropstone-fast, dropstone-pro, dropstone-heavy | | messages | array | sim | Lista de objetos de mensagem com role e content | | stream | boolean | não | Quando true, retorna Server-Sent Events. Padrão false | | temperature | number | não | Temperatura de amostragem, 0..2. Padrão específico do modelo | | max_tokens | number | não | Limite de tokens de saída | | tools | array | não | Esquemas de ferramentas para chamada de função, formato OpenAI | | tool_choice | string \| object | não | "auto", "none" ou uma ferramenta específica |

Exemplo: chat simples

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": "Escreva um haiku sobre depuração."}
    ]
  }'

Resposta

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

O campo usage.cost é o valor cobrado em USD — o que foi deduzido do seu saldo de créditos para esta requisição (custo real do provedor × acréscimo de 1.3).

Streaming

Defina "stream": true para obter um fluxo de Server-Sent Events com os chunks de tokens. O fluxo termina com uma linha data: [DONE] e um chunk final contendo o bloco 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": "Conte até 5."}]
  }'

Compatibilidade com o SDK da OpenAI

Como a superfície é compatível com OpenAI, você pode usar o SDK oficial da OpenAI substituindo o 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": "Olá"}],
)
print(resp.choices[0].message.content)

Códigos de erro

Formato da resposta 402

{
  "error": "Créditos insuficientes",
  "balance": 0,
  "message": "Seu saldo de créditos está vazio. Recarregue em https://dropstone.io/dashboard/billing para continuar.",
  "topUpUrl": "https://dropstone.io/dashboard/billing"
}

Limites de taxa

Não há limites rígidos de taxa aplicados na API hoje. Camadas de uso por chave e limites diários de gastos estão planejados — quando forem lançados, suas chaves existentes serão automaticamente classificadas com base no gasto vitalício, semelhante ao sistema de camadas da OpenAI.

Por enquanto, defina orçamentos por chave você mesmo, rastreando o campo usage.cost no seu aplicativo.

Práticas recomendadas

• Use variáveis de ambiente, nunca chaves inline: DROPSTONE_API_KEY=dsk_live_....
• Uma chave por serviço, não uma chave compartilhada em todos os lugares. Mais fácil de revogar quando um serviço é comprometido.
• Acompanhe usage.cost nas respostas para monitorar gastos em tempo real.
• Lide com 402 com elegância — seu aplicativo deve detectá-lo e exibir um CTA de recarga em vez de tentar novamente.
• Armazene em cache as respostas para requisições idênticas repetidas do seu lado — nós armazenamos em cache no nível do modelo, mas você economiza o acréscimo total ao evitar chegar até nós.

Diferenças da CLI e do SDK

| Superfície | Autenticação | Modelo de preços | Modelos | Caso de uso | |---|---|---|---| | API HTTP (esta página) | Chave de API | Pré-pago a partir do saldo de créditos | Fast / Pro / Heavy | CI, automação, integrações | | CLI (docs) | Login interativo | Assinatura + saldo de créditos | Mesmos três + modelos gratuitos de código aberto | Codificação diária em um terminal | | SDK JS (docs) | Inicia a CLI local, herda sua autenticação | Igual à CLI | Igual à CLI | Incorporar o agente em um aplicativo Node |

Se você quer acesso programático headless em CI ou em um servidor, a API HTTP é a superfície certa. O SDK é para incorporar o agente interativo em um processo Node onde um humano ainda está no comando.

Em breve

Estes itens estão no roadmap e serão lançados sob o mesmo namespace /api/v1:

• POST /api/v1/agent/run — endpoint de loop de agente. Envie uma tarefa, receba um diff finalizado. Loop de múltiplas etapas no servidor com ferramentas integradas (edição de arquivos, busca na web, execução de código). Preço fixo por tarefa.
• POST /api/v1/memory/store + GET /api/v1/memory/query — memória com estado via Qdrant. Contexto do agente que persiste entre chamadas.
• Injeção de ferramentas MCP — inclua suas próprias URLs de servidor MCP nas requisições do agente; o agente as chama como ferramentas nativas.
• Limites de gastos por chave — defina um limite diário em $ por chave a partir do dashboard. Rede de segurança para CI.

Marque o repositório no GitHub ou acompanhe o changelog para saber quando forem lançados.