API HTTP

API HTTP Dropstone memberi Anda akses terprogram ke tiga model yang sama yang digunakan CLI — Dropstone Fast, Pro, dan Heavy — melalui antarmuka yang kompatibel dengan OpenAI. Satu kunci, satu tagihan, tiga keluarga model.

Gunakan API ini ketika Anda ingin memanggil Dropstone dari kode Anda sendiri: pipeline CI, alat internal, otomatisasi, atau aplikasi pihak ketiga. Untuk pengodean interaktif, gunakan CLI sebagai gantinya.

URL Dasar

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

Semua endpoint dipasang di bawah /api/v1. Jalur ini diberi versi sehingga perubahan besar di masa depan akan ditempatkan di bawah /api/v2 tanpa mengganggu kode Anda.

Autentikasi

Setiap permintaan harus menyertakan kunci API di header Authorization:

Authorization: Bearer dsk_live_<your-key>

Membuat kunci

1. Masuk ke dropstone.io/dashboard
2. Buka Settings → API
3. Klik Create key, beri nama (mis. Production CI)
4. Salin kunci lengkap — Anda hanya akan melihatnya sekali

Kunci terlihat seperti dsk_live_<43 chars>. Simpan di pengelola rahasia atau di variabel lingkungan DROPSTONE_API_KEY.

Mencabut kunci

Cabut dari halaman Settings → API yang sama. Pencabutan bersifat langsung; permintaan yang sedang berjalan dengan kunci tersebut tetap dilanjutkan, permintaan baru mendapatkan 401.

Kredit & penagihan

API ini bayar-per-pakai terhadap saldo kredit. Tidak ada tingkat gratis dan tidak ada langganan di permukaan API.

• Beli kredit di dropstone.io/dashboard/billing. Stripe menangani pembayaran.
• Setiap permintaan memotong biayanya dari creditBalance Anda.
• Ketika creditBalance turun ke $0, API mengembalikan 402 Kredit tidak mencukupi sampai Anda mengisi ulang.
• Kredit langganan (jatah bulanan Pro/Teams) dan kuota permintaan gratis tidak berlaku untuk permintaan kunci API.

Harga

Harga adalah biaya inferensi nyata yang diteruskan dengan markup 30% (1.3x). Biaya penuh per permintaan dikembalikan di bidang usage.cost respons, sehingga Anda dapat memverifikasi setiap tagihan.

Token prompt yang di-cache ditagih dengan tarif cache penyedia (biasanya ~5–10% dari tarif input normal), sehingga percakapan multi-putaran menjadi semakin murah.

Model

GET /api/v1/models

Daftarkan tiga tingkat yang tersedia.

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

Respons:

{
  "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 yang kompatibel dengan OpenAI. Jika Anda pernah menggunakan API yang kompatibel dengan OpenAI, ini terlihat identik.

Badan permintaan

| Bidang | Tipe | Wajib | Deskripsi | |---|---|---| | model | string | ya | Salah satu dari dropstone-fast, dropstone-pro, dropstone-heavy | | messages | array | ya | Daftar objek pesan dengan role dan content | | stream | boolean | tidak | Ketika true, mengembalikan Server-Sent Events. Default false | | temperature | number | tidak | Suhu pengambilan sampel, 0..2. Default spesifik model | | max_tokens | number | tidak | Batas token output | | tools | array | tidak | Skema alat pemanggilan fungsi, format OpenAI | | tool_choice | string \| object | tidak | "auto", "none", atau alat tertentu |

Contoh: chat sederhana

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

Respons

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

Bidang usage.cost adalah jumlah yang ditagih dalam USD — apa yang dipotong dari saldo kredit Anda untuk permintaan ini (biaya penyedia nyata × markup 1.3).

Streaming

Atur "stream": true untuk mendapatkan aliran Server-Sent Events dari potongan token. Aliran berakhir dengan baris data: [DONE] dan potongan akhir yang berisi blok usage lengkap.

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

Kompatibilitas SDK OpenAI

Karena permukaannya kompatibel dengan OpenAI, Anda dapat menggunakan SDK OpenAI resmi dengan menimpa 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)

Kode kesalahan

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

Batas laju

Tidak ada batas laju keras yang diberlakukan pada API hari ini. Tingkat penggunaan per-kunci dan batas pengeluaran harian direncanakan — ketika diluncurkan, kunci yang ada akan otomatis diberi tingkat berdasarkan pengeluaran seumur hidup, mirip dengan sistem tingkat OpenAI.

Untuk saat ini, tetapkan anggaran per-kunci sendiri dengan melacak bidang usage.cost di aplikasi Anda.

Praktik yang disarankan

• Gunakan variabel lingkungan, jangan pernah kunci inline: DROPSTONE_API_KEY=dsk_live_....
• Satu kunci per layanan, bukan satu kunci yang dibagikan di mana-mana. Lebih mudah dicabut ketika layanan disusupi.
• Pantau usage.cost dalam respons untuk melacak pengeluaran secara real-time.
• Tangani 402 dengan baik — aplikasi Anda harus mendeteksinya dan menampilkan CTA isi ulang daripada mencoba lagi.
• Cache respons untuk permintaan identik yang berulang di sisi Anda — kami melakukan cache di tingkat model, tetapi Anda menghemat markup penuh dengan memotong sebelum mencapai kami.

Perbedaan dari CLI dan SDK

| Permukaan | Autentikasi | Model harga | Model | Kasus penggunaan | |---|---|---|---| | API HTTP (halaman ini) | Kunci API | Bayar-per-pakai dari saldo kredit | Fast / Pro / Heavy | CI, otomatisasi, integrasi | | CLI (dokumen) | Masuk interaktif | Langganan + saldo kredit | Tiga yang sama + model open-source gratis | Pengodean sehari-hari di terminal | | SDK JS (dokumen) | Memunculkan CLI lokal, mewarisi autentikasinya | Sama seperti CLI | Sama seperti CLI | Menyematkan agen di aplikasi Node |

Jika Anda menginginkan akses terprogram tanpa kepala di CI atau server, API HTTP adalah permukaan yang tepat. SDK untuk menyematkan agen interaktif di proses Node di mana manusia masih dalam lingkaran.

Segera hadir

Ini ada di peta jalan dan akan ditempatkan di bawah namespace /api/v1 yang sama:

• POST /api/v1/agent/run — endpoint loop agen. Kirim tugas, dapatkan diff selesai. Loop multi-putaran sisi server dengan alat bawaan (pengeditan file, pencarian web, eksekusi kode). Harga datar per tugas.
• POST /api/v1/memory/store + GET /api/v1/memory/query — memori stateful melalui Qdrant. Konteks agen yang bertahan di seluruh panggilan.
• Injeksi alat MCP — sertakan URL server MCP Anda sendiri dalam permintaan agen, agen memanggilnya sebagai alat asli.
• Batas pengeluaran per-kunci — tetapkan batas $ harian per kunci dari dashboard. Jaring pengaman CI.

Beri bintang repositori GitHub atau pantau changelog untuk mengetahui kapan mereka diluncurkan.