HTTP API

Dropstone HTTP API는 CLI가 사용하는 동일한 세 가지 모델 — Dropstone Fast, Pro, Heavy — 을 OpenAI 호환 인터페이스로 프로그래밍 방식으로 액세스할 수 있게 해줍니다. 키 하나, 청구서 하나, 세 가지 모델 패밀리.

CI 파이프라인, 내부 도구, 자동화 또는 타사 앱에서 자체 코드로 Dropstone을 호출하려면 API를 사용하세요. 대화형 코딩에는 CLI를 대신 사용하세요.

기본 URL

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

모든 엔드포인트는 /api/v1 아래에 마운트됩니다. 경로에 버전이 지정되어 있어 향후 주요 변경 사항은 코드를 중단하지 않고 /api/v2에 배치됩니다.

인증

모든 요청에는 Authorization 헤더에 API 키가 포함되어야 합니다:

Authorization: Bearer dsk_live_<your-key>

키 생성

1. dropstone.io/dashboard에 로그인
2. 설정 → API 열기
3. 키 생성 클릭, 이름 지정 (예: Production CI)
4. 전체 키 복사 — 한 번만 볼 수 있습니다

키는 dsk_live_<43 chars> 형식입니다. 비밀 관리자 또는 DROPSTONE_API_KEY 환경 변수에 저장하세요.

키 해지

동일한 설정 → API 페이지에서 해지하세요. 해지는 즉시 적용됩니다. 진행 중인 요청은 계속되고 새 요청은 401을 받습니다.

크레딧 및 결제

API는 크레딧 잔액에 대한 사용량 기반 결제입니다. API 표면에는 무료 티어나 구독이 없습니다.

• dropstone.io/dashboard/billing에서 크레딧을 구매하세요. Stripe가 결제를 처리합니다.
• 각 요청은 creditBalance에서 비용을 차감합니다.
• creditBalance가 $0로 떨어지면 충전할 때까지 API는 402 크레딧 부족을 반환합니다.
• 구독 크레딧(Pro/Teams 월간 허용량)과 무료 요청 할당량은 API 키 요청에 적용되지 않습니다.

가격

가격은 30% 마크업(1.3x)이 적용된 실제 추론 비용입니다. 요청당 전체 비용은 응답의 usage.cost 필드에 반환되므로 모든 요금을 확인할 수 있습니다.

캐시된 프롬프트 토큰은 제공업체의 캐시 요율(일반적으로 일반 입력 요율의 510%)로 청구되므로 다중 턴 대화는 점점 저렴해집니다.

모델

GET /api/v1/models

세 가지 사용 가능한 티어를 나열합니다.

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

응답:

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

채팅 완성

POST /api/v1/chat/completions

OpenAI 호환 채팅 완성. OpenAI 호환 API를 사용해 본 적이 있다면 이 API도 동일하게 보입니다.

요청 본문

| 필드 | 유형 | 필수 | 설명 | |---|---|---| | model | string | 예 | dropstone-fast, dropstone-pro, dropstone-heavy 중 하나 | | messages | array | 예 | role 및 content가 있는 메시지 객체 목록 | | stream | boolean | 아니요 | true이면 Server-Sent Events를 반환합니다. 기본값 false | | temperature | number | 아니요 | 샘플링 온도, 0..2. 기본값은 모델별 | | max_tokens | number | 아니요 | 출력 토큰 상한 | | tools | array | 아니요 | 함수 호출 도구 스키마, OpenAI 형식 | | tool_choice | string \| object | 아니요 | "auto", "none" 또는 특정 도구 |

예시: 간단한 채팅

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

응답

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

usage.cost 필드는 USD로 청구된 금액입니다 — 이 요청에 대해 크레딧 잔액에서 차감된 금액(실제 제공업체 비용 × 1.3 마크업)입니다.

스트리밍

"stream": true로 설정하면 토큰 청크의 Server-Sent Events 스트림을 받습니다. 스트림은 data: [DONE] 줄과 전체 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": "Count to 5."}]
  }'

OpenAI SDK 호환성

표면이 OpenAI 호환 방식이므로 base_url을 재정의하여 공식 OpenAI SDK를 사용할 수 있습니다:

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)

오류 코드

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

요율 제한

현재 API에는 강제되는 하드 요율 제한이 없습니다. 키별 사용 티어와 일일 지출 상한이 계획되어 있습니다. 출시되면 기존 키는 OpenAI의 티어 시스템과 유사하게 평생 지출에 따라 자동으로 티어가 지정됩니다.

지금은 애플리케이션에서 usage.cost 필드를 추적하여 키별 예산을 직접 설정하세요.

권장 사례

• 환경 변수 사용, 키를 인라인으로 넣지 마세요: DROPSTONE_API_KEY=dsk_live_....
• 서비스별 키 하나, 모든 곳에서 하나의 키를 공유하지 마세요. 서비스가 손상되었을 때 해지하기 쉽습니다.
• 응답의 usage.cost 확인 — 실시간 지출을 추적하세요.
• 402를 우아하게 처리 — 앱이 이를 감지하고 재시도 대신 충전 CTA를 표시해야 합니다.
• 반복되는 동일 요청에 대한 응답 캐시 — 모델 수준에서 캐시하지만, 우리에게 도달하기 전에 단락시켜 전체 마크업을 절약할 수 있습니다.

CLI 및 SDK와의 차이점

| 표면 | 인증 | 가격 모델 | 모델 | 사용 사례 | |---|---|---|---| | HTTP API (이 페이지) | API 키 | 크레딧 잔액에서 사용량 기반 결제 | Fast / Pro / Heavy | CI, 자동화, 통합 | | CLI (문서) | 대화형 로그인 | 구독 + 크레딧 잔액 | 동일한 세 가지 + 무료 오픈소스 모델 | 터미널에서 일상적인 코딩 | | JS SDK (문서) | 로컬 CLI를 생성, 인증 상속 | CLI와 동일 | CLI와 동일 | Node 앱에 에이전트 임베딩 |

CI 또는 서버에서 헤드리스 프로그래밍 방식 액세스를 원한다면 HTTP API가 올바른 표면입니다. SDK는 사람이 여전히 루프에 있는 Node 프로세스에 대화형 에이전트를 임베딩하기 위한 것입니다.

곧 출시 예정

다음은 로드맵에 있으며 동일한 /api/v1 네임스페이스 아래에 배치될 예정입니다:

• POST /api/v1/agent/run — 에이전트 루프 엔드포인트. 작업을 보내면 완성된 diff를 받습니다. 서버 측 다중 턴 루프와 내장 도구(파일 편집, 웹 검색, 코드 실행)가 포함됩니다. 작업당 고정 가격.
• POST /api/v1/memory/store + GET /api/v1/memory/query — Qdrant를 통한 상태 저장 메모리. 호출 간에 지속되는 에이전트 컨텍스트.
• MCP 도구 주입 — 에이전트 요청에 자체 MCP 서버 URL을 포함하면 에이전트가 네이티브 도구로 호출합니다.
• 키별 지출 상한 — 대시보드에서 키별 일일 $ 한도를 설정합니다. CI 안전망.

GitHub 저장소에 별표를 주거나 변경 로그를 확인하여 출시 시점을 알아보세요.