Ana sayfa/Geliştiriciler/Dokümanlar
Tek API anahtarıyla teklif ara, pod kaldır, canlı maliyeti oku. Aşağıdaki her uç Faz 0 sözleşmesinde tanımlı ve yerel geliştirme sunucusunda çalışıyor. Olmayan bir şeyi burada anlatmıyoruz.
Faz 0 · broker MVP. Uçlar sabit kalır; altındaki arz evrilir.
Önce dürüst durum
Kalıcı doküman sitesi (Fumadocs) sonraki dilimde geliyor. O gelene kadar tek başvuru noktası bu sayfa: yalnızca yazılmış ve çalışan uçları listeler.
Taban adres yerel geliştirmede https://api.kaldera.ai, konsol https://konsol.kaldera.ai. Herkese açık alan adı ilk beta ile duyurulacak.
Hızlı başlangıç
Saat değil saniye ödersin, tavanı baştan koyarsın, istediğin an durdurursun.
Konsolda Hesap → API Anahtarları'ndan bir anahtar üret. Anahtar kld_ ile başlar; tam değeri yalnız üretildiği anda bir kez görünür, sunucuda yalnız özeti (hash) saklanır. Kaybedersen yenisini üretirsin — kurtarma yolu yoktur.
Tek statik binary; Go ile derlenir, çalışma zamanı bağımlılığı yoktur. Adresi KALDERA_API ortam değişkeniyle verirsin (varsayılan https://api.kaldera.ai). Aynı işleri düz curl ile de yapabilirsin; CLI yalnızca ince bir kabuk.
Teklifleri puana göre listele, beğendiğinin kimliğiyle pod yarat. Yaratma isteğine Idempotency-Key koy: ağ koptuğunda aynı anahtar 24 saat boyunca aynı pod'u döner, ikinci kez ücret ödemezsin.
REST uçları
Para her yerde tam sayı mikro-dolar (*_micros): örneğin $0.42/sa değeri 420000 olarak taşınır. Zaman RFC 3339 UTC. Boş liste [] döner, hiçbir zaman null değil.
| Uç | Ne yapar | Döner |
|---|---|---|
| GET /v1/offers | Teklif arar: GPU modeli, VRAM, fiyat tavanı, karne, ülke, bölge grubu, Verified filtreleri | offers[] + facets |
| GET /v1/offers/{id} | Tek teklif ve fiyat kırılımı — saatlik, günlük, aylık | offer + price_breakdown |
| POST /v1/pods | Pod yaratır; Idempotency-Key başlığını okur | 201 pod |
| GET /v1/pods | Pod listesi; ?status=running ile süzülür | pods[] + count |
| GET /v1/pods/{id} | Tek pod: durum, sağlık, bağlantı, maliyet sayacı, bölge sabiti | pod |
| POST /v1/pods/{id}/stop | Durdurur; fatura o saniye durur, kalıcı disk kalır | pod |
| POST /v1/pods/{id}/start | Durdurulmuş pod'u kaldığı yerden başlatır | pod |
| DELETE /v1/pods/{id} | Sonlandırır; ?delete_volume=1 ile kalıcı diski de siler | 204 |
| GET /v1/pods/{id}/logs | SSE. ?follow=true ile canlı log akışı; false ise son 200 satır | event: log |
| GET /v1/pods/{id}/telemetry | SSE. GPU kullanımı, VRAM, sıcaklık, güç, sağlık bayrağı | event: telemetry |
| GET /v1/pods/{id}/metrics | Geçmiş seriler (1h · 6h · 24h · 7d) ve faturalanmayan aralıklar | series[] + health_gaps[] |
| GET /v1/billing/summary | Dönem harcaması, yakım hızı, projeksiyon, bütçe tavanı, garanti iadesi | spent + budget + guarantee |
| GET /v1/billing/live | SSE. Canlı maliyet sayacı — saniyede bir tik | event: cost |
| PUT /v1/billing/budget | Sert tavanı ve tavana gelince davranışı ayarlar: pause ya da notify_only | budget |
| GET /v1/host/machines | Host paneli: makineler, doluluk, kazanç, fiyat önerisi | machines[] |
| GET /healthz | Sağlık probu: servis, veritabanı ve arz havuzu durumu | status + db + supply |
Tam liste — faturalama kalemleri, faturalar, ödeme yöntemi, host karnesi ve payout uçları dahil — depodaki docs/faz0-http-sozlesmesi.md dosyasındadır. Bu tablo o sözleşmenin özetidir, ondan sapmaz.
Örnekler
Aynı üç işi CLI, curl ve Python ile yapabilirsin: teklifleri puanla, pod yarat, maliyeti dinle. Aşağıdaki değerler örnektir; gerçekleri pazar yerinden gelir.
# Teklifleri puana göre listele (çıktı örnektir) $ kaldera offers --min-vram 24 --verified GPU ADET BÖLGE $/SA KARNE PUAN RTX 4090 1 Istanbul 0.42 4.9 0.87 L40S 1 Frankfurt 0.79 4.8 0.64 # Beğendiğini saniye bazlı kirala $ kaldera pod create --offer mock-ist-4090 \ --image kaldera/pytorch:2.4-cuda12.4 ✓ pod_01J8... · running · $0.42/sa
# Teklif ara — AB + TR havuzunda $ curl -s "$KALDERA_API/v1/offers?region_group=eu_tr" \ -H "Authorization: Bearer $KLD_KEY" # Pod yarat — idempotans anahtarıyla $ curl -s -X POST "$KALDERA_API/v1/pods" \ -H "Authorization: Bearer $KLD_KEY" \ -H "Idempotency-Key: 01J8ZQ3M7K" \ -H "Content-Type: application/json" \ -d '{"offer_id":"mock-ist-4090","image":"kaldera/pytorch:2.4-cuda12.4","volume_gb":250}' # Canlı maliyeti dinle (SSE · örnek çıktı) $ curl -N "$KALDERA_API/v1/billing/live" event: cost data: {"spent_micros":47820120,"running_pods":1}
# SDK henüz yok; düz httpx yeter. # Para tam sayı mikro-dolar: 420000 = $0.42 import os, httpx api = os.environ["KALDERA_API"] h = {"Authorization": "Bearer " + os.environ["KLD_KEY"]} r = httpx.get(api + "/v1/offers", headers=h, params={"min_vram_gb": 24, "sort": "score"}) best = r.json()["offers"][0] pod = httpx.post(api + "/v1/pods", headers=h, json={ "offer_id": best["id"], "image": "kaldera/pytorch:2.4-cuda12.4", # $120 sert tavan (örnek) "budget_cap_micros": 120000000, }).json()["pod"] print(pod["id"], pod["status"])
Kimlik doğrulama
CLI ve SDK kld_ ile başlayan API anahtarı taşır: Authorization: Bearer kld_…. Anahtarlar sunucuda hash'li durur, tam değer yalnız yaratılışta bir kez gösterilir. Konsol tarayıcıda HttpOnly oturum çerezi kullanır; iki yol birbirine karışmaz.
Her anahtara yalnız ihtiyacı olan yetkiyi ver: offers:read, pods:write, billing:read, host:write. CI'da koşan anahtarın faturayı okuması gerekmiyorsa okumasın.
Sızdığından şüphelendiğin anda iptal et, yenisini üret. Sunucu yalnız hash'i bildiği için biz de sana anahtarını geri okuyamayız — bu bir eksiklik değil, tasarım.
Dürüst not: Faz 0'da control plane yerel geliştirme için kimlik doğrulaması yapmaz — localhost:8080 açık konuşur. Anahtar üretimi, kapsam denetimi ve hız sınırı ilk beta ile devreye girecek. Örneklerdeki Authorization başlığı hedef sözleşmedir; bugün gönderirsen yok sayılır. Güvenlik kararlarının tamamı Güvenlik sayfasında.
Hatalar
Tüm 4xx/5xx yanıtları aynı gövdeyi döner: code genel sınıf, reason makine-okunur sebep, message insan için, details bağlam. Konsol da senin kodun da reason'a bakarak davranır.
| HTTP | code | reason | Ne demek, ne yapmalı |
|---|---|---|---|
| 400 | invalid_argument | region_pin_violation | İstenen teklif bölge sabitinin dışında. Sunucu tarafı kontroldür, atlanamaz. |
| 400 | invalid_argument | — | Bozuk filtre ya da eksik alan; details hangi alan olduğunu söyler. |
| 402 | resource_exhausted | budget_cap_reached | Sert tavan doldu. Tavanı yükselt ya da bekle; iş çökmez, duraklar. |
| 403 | permission_denied | role_insufficient | Anahtarın kapsamı veya rolün yetmiyor. |
| 404 | not_found | — | Bilinmeyen pod, teklif ya da makine. |
| 409 | failed_precondition | offer_stale | Teklif tazeliğini yitirdi; details.new_price_micros_hour yeni fiyatı taşır — onaylayıp yeniden dene. |
| 409 | failed_precondition | no_payment_method | Bakiye ya da ödeme yöntemi yok. |
| 409 | failed_precondition | pod_not_running | Çalışmayan pod'a, çalışır durum isteyen bir işlem gönderildi. |
| 503 | unavailable | provider_down | Sağlayıcı cevap vermiyor; alternatif tekliflere düş. |
Örnek gövde: {"error":{"code":"failed_precondition","reason":"offer_stale","message":"Teklif tazeliğini yitirdi.","details":{"new_price_micros_hour":445000}}}
SDK ve araçlar
Müşterinin birinci dili Python olduğu için sıra bellidir. O gün gelene kadar düz HTTP çağrısı yapman gerekir; sözleşme küçük olduğu için bu bir külfet değil.
Go ile tek statik binary. Bugün offers, pods, pod create ve version komutları var; log ve ssh komutları henüz yok.
Tip destekli istemci, SSE yardımcıları ve mikro-dolar dönüşümü hazır gelecek. Bugün httpx ile aynı işi yapabilirsin.
Proto üretim hattı bağlanınca ConnectRPC istemcisinden üretilecek, elle yazılmayacak. Konsol da aynı istemciyi kullanacak.
Terraform sağlayıcısı ve SkyPilot entegrasyonu yol haritasında; henüz yazılmadı, tarih vermiyoruz. Bu sitede bir şeyin yanında "yakında" yazıyorsa o şey gerçekten yoktur.
Başla
Çalışmayan saniyeye para yok, sert bütçe tavanı, saniye bazlı fatura — üçü de API'nin içinde, sonradan yamanan özellikler değil.