Kedy API Dokümantasyonu

01Kedy API’ye genel bakış

Kedy API, uygulamanızın NOVAQ modeline bir metin isteği göndermesini sağlar. Bu rehber; hesap oluşturmayı, API anahtarınızı kullanmayı, ilk isteğinizi göndermeyi ve yanıtı sunucunuzda işlemeyi anlatır. Örnekler, Çiçekli Teknolig katılımcı rehberinde kullanılan temel istek biçimini takip eder.

İlk kez kullanıyorsanız hızlı başlangıç bölümünden ilerleyin. İstek alanlarını incelemek için API referansına, bir hatayı araştırmak için hata giderme bölümüne geçin.

02Hızlı başlangıç

1. chat.kedy.dev üzerinden hesabınızı oluşturun ve giriş yapın.
2. Aynı platform üzerinden bir API anahtarı oluşturun.
3. Anahtarı, aşağıdaki örnekteki YOUR_API_KEY yerine kullanarak terminal oturumunuza tanıtın.
4. İstek komutunu çalıştırın. Başarılı istekte JSON yanıtını terminalde görebilirsiniz.

macOS / Linux

export KEDY_API_KEY="YOUR_API_KEY"

curl https://api.kedy.dev/v1/chat/completions \
  -H "Authorization: Bearer $KEDY_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 30 \
  -d '{"model":"novaq","messages":[{"role":"user","content":"Hello"}]}'

Windows · PowerShell

$env:KEDY_API_KEY = "YOUR_API_KEY"

$body = @{
  model = "novaq"
  messages = @(@{ role = "user"; content = "Hello" })
} | ConvertTo-Json -Depth 6

Invoke-RestMethod `
  -Uri "https://api.kedy.dev/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:KEDY_API_KEY" } `
  -ContentType "application/json" `
  -Body $body `
  -TimeoutSec 30

macOS / Linux örneği cURL gerektirir. Windows örneği PowerShell’in yerleşik HTTP komutunu kullanır. content değerini değiştirerek kendi metninizi gönderebilirsiniz.

03API anahtarı ve kimlik doğrulama

API anahtarı, uygulamanızın Kedy API’ye erişirken kullandığı gizli değerdir. Her istekte anahtarı Authorization başlığına, başında Bearer ve bir boşluk olacak şekilde ekleyin.

Authorization: Bearer YOUR_API_KEY

• Anahtarı sunucunuzun ortam değişkeninde saklayın: KEDY_API_KEY.
• Frontend JavaScript dosyalarına, mobil uygulama paketine veya herkese açık repolara eklemeyin.
• Tarayıcı, Kedy API’ye doğrudan bağlanmak yerine kendi backend’inize istek göndermelidir.
• Anahtarı ekran görüntülerinde, hata kayıtlarında veya geliştirme araçlarına verdiğiniz promptlarda paylaşmayın.

Yerel geliştirme dosyaları

Bir .env dosyası kullanıyorsanız onu sürüm kontrolünden çıkarın. Ekibiniz için yalnızca yer tutucu içeren bir .env.example paylaşın.

.env
.env.*
!.env.example

KEDY_API_KEY=YOUR_API_KEY

04API referansı

Bu sayfadaki örnekler aşağıdaki endpoint’e JSON gövdesiyle POST isteği gönderir. Temel adres https://api.kedy.dev, endpoint yolu /v1/chat/completions ve model kimliği novaq şeklindedir.

{
  "model": "novaq",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}

05Node.js ile istek gönderme

Bu örnek Node.js 22 veya üstünde yerleşik fetch ile çalışır; paket kurulumu gerektirmez. Kodu request.mjs adıyla kaydedin. Hızlı başlangıçtaki komutla anahtarınızı aynı terminal oturumunda tanımlayın, ardından dosyayı çalıştırın.

const apiKey = process.env.KEDY_API_KEY;
if (!apiKey) throw new Error('Set KEDY_API_KEY first.');

const response = await fetch('https://api.kedy.dev/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'novaq',
    messages: [{ role: 'user', content: 'Hello' }]
  }),
  signal: AbortSignal.timeout(30_000)
});

if (!response.ok) {
  throw new Error(`Kedy API returned HTTP ${response.status}.`);
}
const data = await response.json();
const reply = data.choices?.[0]?.message?.content;
if (typeof reply !== 'string' || !reply.trim()) {
  throw new Error('The response did not contain a text message.');
}
console.log(reply);

node request.mjs

Kod; anahtarın varlığını kontrol eder, JSON isteğini gönderir, başarısız HTTP durumlarını hata olarak ele alır ve yanıtın metin içerdiğini doğrular. Bağlantı veya zaman aşımı hatası oluşursa fetch hata verir. Uygulamanıza eklerken bu işlemi kendi hata yönetiminizle sarın.

06Python ile istek gönderme

Bu örnek Python 3’ün standart kütüphanesini kullanır; ek paket kurulumu gerekmez. Kodu request.py adıyla kaydedin ve API anahtarını aynı terminal oturumunda tanımladıktan sonra çalıştırın.

import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("KEDY_API_KEY")
if not api_key:
    raise SystemExit("Set KEDY_API_KEY first.")

payload = {
    "model": "novaq",
    "messages": [{"role": "user", "content": "Hello"}],
}
request = urllib.request.Request(
    "https://api.kedy.dev/v1/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(request, timeout=30) as response:
        data = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"Kedy API returned HTTP {error.code}.") from None
except (urllib.error.URLError, TimeoutError):
    raise SystemExit("Connection failed or timed out.") from None
except json.JSONDecodeError:
    raise SystemExit("The response was not valid JSON.") from None

try:
    reply = data["choices"][0]["message"]["content"]
except (KeyError, IndexError, TypeError):
    raise SystemExit("The response did not contain a text message.") from None
if not isinstance(reply, str) or not reply.strip():
    raise SystemExit("The response did not contain a text message.")
print(reply)

python3 request.py

py request.py

İstek gövdesi UTF-8 olarak kodlanır. Örnek; HTTP hatalarını, bağlantı sorunlarını, zaman aşımını, geçersiz JSON’u ve metin içermeyen yanıtları ayrı ayrı kontrol eder.

07Yanıtı okuma

Önce HTTP durumunu kontrol edin; ardından JSON gövdesini okuyun. Aşağıdaki sadeleştirilmiş örnek, kod örneklerinin metni okuduğu choices[0].message.content yolunu gösterir. Gerçek yanıtın ek alanları ve içerikleri değişebilir.

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      }
    }
  ]
}

• choices dizisinin dolu olduğunu kontrol edin.
• message.content değerinin metin olduğunu doğrulayın.
• Boş veya beklenmedik yanıtlar için anlaşılır bir hata gösterin.
• Model çıktısını arayüzde düz metin olarak gösterin. HTML olarak işleyecekseniz güvenli biçimde temizleyin.
• Model çıktısını otomatik bir işlemde kullanacaksanız beklenen formatı ayrıca doğrulayın.

08Hata giderme

Bir istek başarısız olursa HTTP durumunu ve hata mesajını kontrol edin. Aşağıdaki tablo genel HTTP durumlarına göre inceleme adımlarını gösterir; API’den gelen gerçek hata gövdesi ek bilgi verebilir.

Terminal çalışıyor, uygulama çalışmıyor

Sunucunuzun ortam değişkenini okuyabildiğini ve istek gövdesinin cURL örneğiyle aynı alanları taşıdığını kontrol edin. Tarayıcıdan doğrudan Kedy API’ye istek atıyorsanız isteği backend’e taşıyın. Günlüklerde durum kodunu kaydedin; API anahtarını veya kişisel mesajları kaydetmeyin.

09Projenize entegre etme

Örnek isteği çalıştırdıktan sonra aynı işlemi sunucunuzdaki bir endpoint veya sunucu fonksiyonuna taşıyın. Arayüzünüz yalnızca kendi sunucunuza bağlansın; Kedy API anahtarı sunucuda kalsın.

1. Girdiyi doğrulayın. Boş girdileri reddedin ve uygulamanıza uygun bir uzunluk sınırı belirleyin.
2. Anahtarı sunucuda okuyun. KEDY_API_KEY eksikse anlaşılır bir yapılandırma hatası üretin.
3. API isteğini gönderin. İstek gövdesini JSON.stringify veya json.dumps gibi bir JSON dönüştürücüyle hazırlayın.
4. Yanıtı doğrulayın. HTTP durumunu, JSON formatını ve metin alanını kontrol edin.
5. Sonucu gösterin. Yüklenme, başarı ve hata durumlarını ayrı ele alın. Aynı işlem sürerken tekrar gönderimi engelleyin.
6. Kullanımı kontrol edin. Herkese açık bir backend için kendi kimlik doğrulamanızı ve istek sınırlamanızı ekleyin.

Yayınlamadan önce

• API anahtarını hosting sağlayıcınızın sunucu ortam değişkenlerine ekleyin.
• Yerel .env dosyanızın sunucuya otomatik taşınacağını varsaymayın.
• Gizli değer içeren ortam değişkenlerini frontend’e açan bir isimlendirme veya yapılandırma kullanmayın.
• Boş girdi, eksik anahtar, HTTP hatası ve zaman aşımı durumlarını deneyin.
• Üretim günlüklerinde anahtarın görünmediğini kontrol edin.

10Sık sorulan sorular ve destek

Ek yardım için Kedy iletişim sayfasına ulaşabilirsiniz. Yarışmaya ilişkin videolar ve katılımcı bilgileri için Çiçekli Teknolig rehberine dönün.