HTTP API

HTTP API Dropstone предоставляет программный доступ к тем же трем моделям, которые использует CLI — Dropstone Fast, Pro и Heavy — через интерфейс, совместимый с OpenAI. Один ключ, один счет, три семейства моделей.

Используйте API, когда хотите вызывать Dropstone из собственного кода: CI-пайплайны, внутренние инструменты, автоматизация или сторонние приложения. Для интерактивного программирования используйте CLI.

Базовый URL

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

Все конечные точки находятся в пространстве /api/v1. Путь версионирован, поэтому будущие критические изменения появятся в /api/v2, не нарушая ваш код.

Аутентификация

Каждый запрос должен содержать API-ключ в заголовке Authorization:

Authorization: Bearer dsk_live_<your-key>

Создание ключа

1. Войдите в dropstone.io/dashboard
2. Откройте Settings → API
3. Нажмите Create key, дайте ему имя (например, Production CI)
4. Скопируйте полный ключ — вы увидите его только один раз

Ключи выглядят как dsk_live_<43 символа>. Храните их в менеджере секретов или в переменной окружения DROPSTONE_API_KEY.

Отзыв ключа

Отзовите ключ на той же странице Settings → API. Отзыв происходит немедленно; текущие запросы с этим ключом продолжают выполняться, новые запросы получают 401.

Кредиты и оплата

API работает по модели оплаты по мере использования с кредитного баланса. На API нет бесплатного тарифа и подписки.

• Покупайте кредиты на dropstone.io/dashboard/billing. Обработку платежей выполняет Stripe.
• Каждый запрос списывает свою стоимость с вашего creditBalance.
• Когда creditBalance падает до $0, API возвращает 402 Insufficient credits, пока вы не пополните баланс.
• Кредиты по подписке (ежемесячный лимит Pro/Teams) и квоты бесплатных запросов не применяются к запросам через API-ключ.

Цены

Цены отражают реальную стоимость инференса с наценкой 30% (1.3x). Полная стоимость каждого запроса возвращается в поле usage.cost ответа, так что вы можете проверить каждое списание.

Кэшированные токены промпта тарифицируются по кэш-ставке провайдера (обычно ~5–10% от обычной ставки входных токенов), поэтому многоходовые диалоги становятся дешевле с каждым шагом.

Модели

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 чат-завершения. Если вы использовали любой API, совместимый с OpenAI, это выглядит идентично.

Тело запроса

Пример: простой чат

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 — это списанная сумма в долларах США — то, что было вычтено из вашего кредитного баланса за этот запрос (реальная стоимость провайдера × наценка 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, вы можете использовать официальный OpenAI SDK, переопределив 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)

Коды ошибок

Формат ответа 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 корректно — ваше приложение должно обнаруживать эту ошибку и показывать призыв к пополнению баланса, а не повторять запрос.
• Кэшируйте ответы для повторяющихся идентичных запросов на своей стороне — мы кэшируем на уровне модели, но вы экономите полную наценку, если обходите нас.

Отличия от CLI и SDK

Если вам нужен безголовый программный доступ в 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-инструментов — включайте URL ваших собственных MCP-серверов в запросы агента, агент вызывает их как нативные инструменты.
• Лимиты расходов на ключ — установите дневной лимит в $ на ключ из дашборда. Страховка для CI.

Поставьте звезду репозиторию GitHub или следите за журналом изменений, чтобы узнать о выходе этих функций.