Dokümantasyon

Karınca Labs API'ye Hoş Geldiniz.

Karınca Labs, Anthropic'in Claude modellerini tek bir API anahtarıyla kullanmanızı sağlar. OpenAI ve Anthropic biçimlerini birlikte desteklediği için Cursor, Cline, Claude Code ve Kilo Code gibi araçlara yalnızca adresi ve anahtarı değiştirerek bağlanırsınız.

Hızlı Başlangıç

1. Hesap oluşturun

   karincalabs.com üzerinden ücretsiz hesabınızı açın.

2. Lisans kodunuzu alın

   Size uygun paketi Fiyatlandırma sayfasından inceleyip karincalisans.com üzerinden satın alın. Lisans kodunuz size iletilir.

3. Kodu aktive edin

   Hesabım → Kod Kullan sayfasına kodu girin. Bakiyeniz ve erişim süreniz otomatik olarak yüklenir.

4. API anahtarınızı kopyalayın

   Hesabım → API Anahtarları sayfasında size özel anahtar hazırdır. Anahtar sk-karinca_ ile başlar.

5. Aracınıza bağlayın

   Kullandığınız araca Karınca Labs panelinden aldığınız anahtarı ve aşağıdaki adresi girin. Araca özel adımlar için Kurulum Rehberleri bölümüne bakın.

Temel Bilgiler

Base URL (OpenAI)

https://api.karincalabs.com/v1Kopyala

Base URL (Anthropic)

https://api.karincalabs.comKopyala

Kimlik doğrulama

Authorization: Bearer sk-karinca_xxxxxxxxxxxxxxxx

Alternatif başlık

x-api-key: sk-karinca_xxxxxxxxxxxxxxxx

Anahtarın yeri

Hesabım → API Anahtarları

İlk isteğiniz

Anahtarınızı yerleştirip terminalde çalıştırın; yanıt birkaç saniye içinde gelir.

1curl https://api.karincalabs.com/v1/chat/completions \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer sk-karinca_xxxxxxxxxxxxxxxx" \4  -d '{5    "model": "claude-opus-5",6    "messages": [{ "role": "user", "content": "Merhaba!" }]7  }'

Başlarken

API Kullanımı

Tüm istekler aynı sunucuya gider. Kullandığınız aracın hangi biçimle konuştuğuna göre adresin sonuna /v1 eklemeniz gerekip gerekmediği değişir.

Base URL

Kimlik Doğrulama

Her istekte API anahtarınızı gönderin. İki başlık da tüm uç noktalarda kabul edilir; aracınız hangisini kullanıyorsa o yeterlidir.

Ortam değişkenleri

Resmî SDK'lar bu değişkenleri otomatik okur; kodda anahtar tutmanıza gerek kalmaz.

1export OPENAI_BASE_URL="https://api.karincalabs.com/v1"2export OPENAI_API_KEY="sk-karinca_xxxxxxxxxxxxxxxx"

Desteklenen uç noktalar

• POST/v1/chat/completionsSohbet tamamlama (OpenAI)
• POST/v1/messagesMesaj oluşturma (Anthropic)
• GET/v1/modelsModel listesi

Başlarken

Endpoint Referansı

Her uç noktanın zorunlu alanları, örnek isteği ve örnek yanıtı.

Chat Completions

OpenAI Chat Completions biçimi. Tüm modellerde çalışır; yalnızca model alanını değiştirmeniz yeterlidir.

1{2  "model": "claude-opus-5",3  "messages": [4    { "role": "system", "content": "Kısa ve net yanıt ver." },5    { "role": "user", "content": "Merhaba!" }6  ],7  "max_tokens": 1024,8  "temperature": 0.79}

Messages (Anthropic)

Anthropic Messages biçimi. Claude Code, Claude Desktop ve Anthropic SDK bu uç noktayı kullanır. Diğer model aileleri de bu biçimle çağrılabilir.

1{2  "model": "claude-opus-5",3  "max_tokens": 1024,4  "system": "Kısa ve net yanıt ver.",5  "messages": [6    { "role": "user", "content": "Merhaba!" }7  ]8}

Models

Hesabınızın kullanabileceği modelleri OpenAI biçiminde listeler. Her kayıtta bağlam penceresi (context_length) ve en fazla çıktı (max_output_tokens) bilgisi de bulunur.

1curl https://api.karincalabs.com/v1/models \2  -H "Authorization: Bearer sk-karinca_xxxxxxxxxxxxxxxx"

Başlarken

Kredi Sistemi

Kullanım, hesabınıza yüklenen bakiye üzerinden ücretlendirilir. Her istek, kullandığı token sayısı ve modelin tarifesine göre bakiyenizden düşer.

İstek akışı

Her istek üç aşamadan geçer:

1. Ön ayırma

   İstek geldiğinde, isteğin boyutuna göre hesaplanan küçük bir tutar bakiyenizde ayrılır. Bakiye yetmiyorsa istek 402 INSUFFICIENT_BALANCE ile reddedilir.

2. İletim

   İstek seçtiğiniz modele iletilir ve yanıt size aktarılır.

3. Kesinleştirme veya iade

   Başarılı yanıtta gerçek token kullanımı kadar ücret düşülür, ayrılan tutarın fazlası geri döner. Hata dönen isteklerde ayrılan tutarın tamamı iade edilir.

Ücret nasıl hesaplanır?

1ücret = (girdi × girdi fiyatı2       + çıktı × çıktı fiyatı3       + önbellekten okunan × önbellek okuma fiyatı4       + önbelleğe yazılan × önbellek yazma fiyatı) ÷ 1.000.000

Erişim süresi

Her paketin bir erişim süresi vardır. Süre dolduğunda API ve sohbet erişimi kapanır, kullanılmayan bakiye de sona erer. Yeni bir paket kodu girerek erişimi ve bakiyeyi birlikte yenileyebilirsiniz. Süre ve bakiye durumunuzu Lisans sayfasında görürsünüz.

Bakiye takibi

Güncel bakiyenizi ve tüm yükleme/harcama hareketlerini Hesabım → Faturalama sayfasında izleyebilirsiniz.

Başlarken

Model Fiyatları

Fiyatlar 1 milyon token başına düşülen bakiye tutarıdır. Kısa istemler ve önbellekten okunan içerik çok daha düşük maliyetlidir.

Kullanım

Örnek Kodlar

Aynı isteğin farklı dillerdeki karşılığı. Seçtiğiniz dil sayfadaki tüm örneklerde hatırlanır.

1curl https://api.karincalabs.com/v1/chat/completions \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer sk-karinca_xxxxxxxxxxxxxxxx" \4  -d '{5    "model": "claude-opus-5",6    "messages": [7      { "role": "user", "content": "Bana üç maddede Python öğrenme planı yaz." }8    ],9    "max_tokens": 102410  }'

Kullanım

Streaming Kullanımı

Yanıtı üretildikçe almak için istek gövdesine stream: true ekleyin. Yanıt SSE (Server-Sent Events) olarak parça parça gelir.

cURL ile streaming

1curl https://api.karincalabs.com/v1/chat/completions \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer sk-karinca_xxxxxxxxxxxxxxxx" \4  --no-buffer \5  -d '{6    "model": "claude-opus-5",7    "messages": [{ "role": "user", "content": "Kısa bir şiir yaz." }],8    "stream": true9  }'

Her parça data: ile başlayan bir JSON satırıdır. Akış data: [DONE] satırıyla biter:

1data: {"choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}2 3data: {"choices":[{"index":0,"delta":{"content":"Karınca"}}]}4 5data: {"choices":[{"index":0,"delta":{"content":" yolda..."}}]}6 7data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}8 9data: [DONE]

Kod ile streaming

1const res = await fetch("https://api.karincalabs.com/v1/chat/completions", {2  method: "POST",3  headers: {4    "Content-Type": "application/json",5    "Authorization": "Bearer " + process.env.KARINCA_API_KEY,6  },7  body: JSON.stringify({8    model: "claude-opus-5",9    messages: [{ role: "user", content: "Kısa bir şiir yaz." }],10    stream: true,11  }),12});13 14const reader = res.body.getReader();15const decoder = new TextDecoder();16let buffer = "";17 18while (true) {19  const { done, value } = await reader.read();20  if (done) break;21 22  buffer += decoder.decode(value, { stream: true });23  const lines = buffer.split("\n");24  buffer = lines.pop() ?? ""; // yarım kalan satırı sonraki parçaya bırak25 26  for (const line of lines) {27    if (!line.startsWith("data:")) continue;28    const data = line.slice(5).trim();29    if (data === "[DONE]") continue;30 31    const chunk = JSON.parse(data);32    const text = chunk.choices?.[0]?.delta?.content;33    if (text) process.stdout.write(text);34  }35}

Anthropic biçiminde streaming

/v1/messages akışı adlandırılmış olaylarla gelir. Metin content_block_delta olaylarında, token kullanımı message_delta olayında yer alır:

1event: message_start2data: {"type":"message_start","message":{"id":"msg_01H8x2","role":"assistant","model":"claude-opus-5"}}3 4event: content_block_delta5data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Karınca yolda..."}}6 7event: message_delta8data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":14}}9 10event: message_stop11data: {"type":"message_stop"}

Kullanım

Hata Yönetimi

Hatalarda HTTP durum kodu ve yanıt gövdesindeki code alanı birlikte sorunun kaynağını gösterir.

HTTP durum kodları

Karınca Labs hata kodları

Yanıt gövdesindeki code alanı aşağıdaki değerlerden birini alır:

Hata yanıt biçimi

1{2  "ok": false,3  "code": "INSUFFICIENT_BALANCE",4  "message": "Insufficient balance for the current user.",5  "userMessage": "Kullanım bakiyeniz yetersiz. Devam etmek için hesabınızdan yeni paket satın alın."6}

message geliştiriciler için teknik açıklamadır; userMessage ise son kullanıcıya gösterebileceğiniz Türkçe metindir. Model sağlayıcısından doğrudan aktarılan bazı hatalar OpenAI ({"error": {...}}) veya Anthropic ({"type": "error", ...}) biçiminde gelebilir.

Yeniden deneme önerisi

429, 502 ve 503 geçici hatalardır; artan bekleme süresiyle (üstel geri çekilme) tekrar deneyin. 400, 401, 402 ve 403 hatalarını tekrar denemek sonucu değiştirmez; önce nedenini giderin.

1async function withRetry(send, maxAttempts = 5) {2  for (let attempt = 1; ; attempt++) {3    const res = await send();4    const retryable = [429, 502, 503].includes(res.status);5    if (!retryable || attempt === maxAttempts) return res;6 7    // Retry-After varsa ona uy, yoksa 1, 2, 4, 8 sn bekle8    const retryAfter = Number(res.headers.get("retry-after"));9    const waitMs = retryAfter > 0 ? retryAfter * 1000 : 2 ** (attempt - 1) * 1000;10    await new Promise((resolve) => setTimeout(resolve, waitMs));11  }12}

Kullanım

SDK Kullanımı

Resmî Anthropic ve OpenAI SDK'ları değişiklik gerekmeden çalışır. Yalnızca adres ve anahtar parametrelerini verin.

Anthropic SDK

1curl https://api.karincalabs.com/v1/messages \2  -H "Content-Type: application/json" \3  -H "x-api-key: sk-karinca_xxxxxxxxxxxxxxxx" \4  -H "anthropic-version: 2023-06-01" \5  -d '{6    "model": "claude-opus-5",7    "max_tokens": 1024,8    "messages": [{ "role": "user", "content": "Merhaba!" }]9  }'

Anthropic SDK ile streaming

1with client.messages.stream(2    model="claude-opus-5",3    max_tokens=1024,4    messages=[{"role": "user", "content": "Kısa bir şiir yaz."}],5) as stream:6    for text in stream.text_stream:7        print(text, end="", flush=True)

OpenAI SDK

OpenAI SDK'sında adresin sonunda /v1 bulunmalıdır. Claude modellerini bu istemciyle de çağırabilirsiniz; model alanına Claude kimliğini yazmanız yeterli.

1# pip install openai2from openai import OpenAI3 4client = OpenAI(5    base_url="https://api.karincalabs.com/v1",6    api_key="sk-karinca_xxxxxxxxxxxxxxxx",7)8 9response = client.chat.completions.create(10    model="claude-opus-5",11    messages=[{"role": "user", "content": "Merhaba!"}],12)13 14print(response.choices[0].message.content)

Kurulum Rehberleri

Cursor Kurulumu

Cursor, OpenAI uyumlu sağlayıcıları destekler. Aşağıdaki adımlarla Karınca Labs modellerini Cursor'un sohbet ve agent pencerelerinde kullanabilirsiniz.

1. Model ayarlarını açın

   Cursor'da Cursor Settings → Models bölümüne gidin.

2. API anahtarınızı girin

   OpenAI API Key alanına Karınca Labs panelinden aldığınız anahtarı yapıştırın ve seçeneği açın.

3. Base URL'i değiştirin

   Override OpenAI Base URL seçeneğini açıp şu adresi girin:

   urlKopyala

   1https://api.karincalabs.com/v1

4. Modeli önekle ekleyin

   Add Custom Model ile kullanmak istediğiniz modeli, başına karinca- ekleyerek girin. Örnek: karinca-claude-opus-5

5. Doğrulayın ve seçin

   Verify ile anahtarı doğrulayın, ardından sohbet penceresindeki model listesinden eklediğiniz modeli seçin.

Kurulum Rehberleri

Cline Kurulumu

Cline eklentisini VS Code veya Antigravity içinde Karınca Labs'e bağlamak için aşağıdaki adımları izleyin.

1. Üyelik ve lisans aktivasyonu

   karincalabs.com üzerinden üyelik oluşturun. Ardından Hesabım → Kod Kullan sayfasına size iletilen lisans kodunu girerek aktivasyonu tamamlayın.

2. API anahtarınızı alın

   Aktivasyondan sonra API Anahtarları bölümüne girin ve size özel oluşturulan anahtarı kopyalayın.

3. Cline'ı yükleyin

   VS Code veya Antigravity içinde Eklentiler bölümünden Cline'ı yükleyin.

4. Claude modelleri için ayarları yapın

   Cline'ın Settings bölümünü açın:

   • API Provider olarak Anthropic seçin.
   • Anthropic API Key alanına Karınca Labs panelinden aldığınız anahtarı girin.
   • Use custom base URL seçeneğini açın ve şu adresi yazın: https://api.karincalabs.comKopyala
   • Model listesinden bir Claude modeli seçin.
   • Enable thinking seçeneğini açıp çubuğu en yüksek seviyeye getirin.

5. OpenAI Compatible ile bağlanmak isterseniz (isteğe bağlı)

   Anthropic sağlayıcısı yerine OpenAI Compatible da kullanabilirsiniz. Önbellek ve görsel desteği için Anthropic sağlayıcısı önerilir:

   • Base URL: https://api.karincalabs.com/v1Kopyala (sondaki /v1 zorunludur)
   • API Key: aynı Karınca Labs anahtarınız; tek anahtar iki sağlayıcıda da geçerlidir.
   • Model ID: tam model adı, ör. claude-opus-5

6. Kurulumu tamamlayın

   Ayarları bitirdikten sonra sağ üstteki Done butonuna tıklayın.

Kurulum Rehberleri

Claude Code Kurulumu

Claude Code, Anthropic Messages biçimini kullanır. Karınca Labs bu biçimi desteklediği için Claude Code'u doğrudan bizim üzerimizden çalıştırabilirsiniz.

1. Claude Code'u yükleyin

   Node.js 18 veya üzeri kuruluysa:

   bashKopyala

   1npm install -g @anthropic-ai/claude-code

2. Ayar dosyasına bağlantı bilgilerini ekleyin

   macOS / Linux'ta ~/.claude/settings.json, Windows'ta %USERPROFILE%\.claude\settings.json dosyasını açın. Dosya zaten varsa mevcut ayarları silmeden env bloğunu ekleyin:

   jsonsettings.jsonKopyala

   1{2  "env": {3    "ANTHROPIC_BASE_URL": "https://api.karincalabs.com",4    "ANTHROPIC_API_KEY": "sk-karinca_xxxxxxxxxxxxxxxx",5    "ANTHROPIC_MODEL": "claude-opus-5",6    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"7  }8}

3. Claude Code'u başlatın

   Proje klasörünüzde claude komutunu çalıştırın. İlk açılışta özel API anahtarını kullanmak isteyip istemediğiniz sorulursa Yes seçin.

4. Modeli değiştirin (isteğe bağlı)

   Oturum içinde /model <model-kimliği> komutuyla başka bir Claude modeline geçebilirsiniz, ör. /model claude-sonnet-5.

Tek seferlik kullanım

Ayar dosyasına dokunmadan yalnızca o terminal oturumu için:

1export ANTHROPIC_BASE_URL="https://api.karincalabs.com"2export ANTHROPIC_API_KEY="sk-karinca_xxxxxxxxxxxxxxxx"3export ANTHROPIC_MODEL="claude-opus-5"4claude

Kurulum Rehberleri

Claude Desktop Kurulumu

Claude Desktop uygulamasını Karınca Labs'e bağlayarak modelleri doğrudan masaüstü arayüzünden kullanabilirsiniz.

1. Geliştirici modunu açın

1. Ana menüyü açın

   Claude Desktop'ın sol üst köşesindeki ana menüye tıklayın.

2. Geliştirici modunu etkinleştirin

   Help → Troubleshooting → Enable Developer Mode yolunu izleyin.

3. Yeniden başlatmayı bekleyin

   Uygulama kapanıp yeniden açılır; bu beklenen bir davranıştır.

2. Karınca Labs bağlantısını yapılandırın

1. Üçüncü taraf ayarını açın

   Menüde yeni beliren Developer başlığı altından Configure third-party inference… seçeneğine tıklayın.

2. Gateway'i seçip bilgileri girin

   Sağlayıcı türü olarak Gateway seçin ve alanları doldurun:

   Base URL

   https://api.karincalabs.comKopyala

   API Key

   Karınca Labs panelinden aldığınız anahtar

3. Kaydedip model seçin

   Ayarları kaydedin. Model seçim alanından bir Claude modeli seçerek kullanmaya başlayabilirsiniz.

Kurulum Rehberleri

Kilo Code Kurulumu

Kilo Code, OpenAI uyumlu sağlayıcıları destekler. Birkaç adımda Karınca Labs'e bağlanır.

1. Eklentiyi yükleyin

   VS Code'da Eklentiler bölümünden Kilo Code'u yükleyin.

2. Sağlayıcıyı seçin

   Kilo Code ayarlarında API Provider olarak OpenAI Compatible seçin.

3. Adresi girin

   Base URL: https://api.karincalabs.com/v1Kopyala

4. Anahtarı girin

   API Key alanına Karınca Labs panelinden aldığınız anahtarı yapıştırın.

5. Modeli yazın ve kaydedin

   Model alanına tam model adını girin (ör. claude-opus-5), ayarları kaydedip kullanmaya başlayın.

Kurulum Rehberleri

Diğer Araçlar

OpenAI veya Anthropic uyumlu adres girilebilen her araç Karınca Labs ile çalışır. Sık kullanılan araçlar için ayar noktaları:

Referans

Desteklenen Modeller

Karınca Labs yalnızca Anthropic'in Claude modellerini sunar. İsteklerde model alanına aşağıdaki kimliklerden birini yazın; hepsi /v1/messages ve /v1/chat/completions ile çalışır.

Referans

Limitler ve Kullanım

Limitler API anahtarı başına uygulanır. Aşıldığında istek reddedilir ama bakiyenizden ücret düşülmez.

Limit başlıkları

Her yanıtta kalan istek hakkınız döner. x-ratelimit-reset, sayacın sıfırlanmasına kalan saniyedir.

1x-ratelimit-limit: 302x-ratelimit-remaining: 273x-ratelimit-reset: 424x-karinca-request-id: 5873a0bf-d4e5-477e-9d23-e9a81c359baa

Kullanım takibi

Bakiyenizi ve harcama geçmişinizi Faturalama, kalan erişim sürenizi Lisans sayfasında izleyebilirsiniz.

Referans

Sıkça Sorulan Sorular