🚀 Hızlı Başlangıç

5 dakikada ilk API çağrınızı yapın: anahtar alın, bir istek gönderin.

1. API anahtarı alın

API sayfasından giriş yapıp API Anahtarı bölümünden anahtar oluşturun. Anahtarı güvenli saklayın; isteklerde Authorization: Bearer <API_KEY> header'ı ile gönderin.

2. Base URL

https://www.numexai.com.tr/api/v1 — tüm endpoint'ler bu önek ile başlar.

3. İlk Chat isteği (curl)

curl -X POST https://www.numexai.com.tr/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"message":"Merhaba, kendini kısaca tanıt","history":[]}'

Başarılı yanıtta answer alanında model yanıtı gelir. Detaylar için Giriş ve Chat endpoint bölümlerine bakın.

API Referansı

Numex AI API, uygulamalarınıza Türkçe yapay zeka yetenekleri eklemenizi sağlar. RESTful HTTP arayüzü, JSON yanıtları ve tüm modaliteler için tek bir API anahtarı.

🔑 Kimlik Doğrulama

Numex AI API, Bearer token kimlik doğrulaması kullanır. Tüm isteklere Authorization başlığını eklemeniz gerekir.

KopyalaAuthorization: Bearer nx_live_your-api-key-here
Content-Type: application/json

API Anahtarı Formatı

Tüm Numex API anahtarları nx_live_ önekiyle başlar ve ardından rastgele bir karakter dizisi gelir:

# Örnek format (gerçek değil)
nx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2

🌐 Base URL

Tüm API istekleri HTTPS üzerinden aşağıdaki base URL'e yapılmalıdır:

https://www.numexai.com.tr/api/v1

🤖 Modeller

Web arayüzünde 4 ana profil (Pro, Fast, Vision, Code) vardır; Developer API'de ek olarak numex-think (akıl yürütme) kullanılabilir. Model seçimi kalite, hız ve maliyet dengesini etkiler.

💬 Chat

Çok turlu sohbet ve geçmiş bağlamı ile AI yanıtı almak için kullanılan temel endpoint. Numex'in boru (pipeline) sistemi üzerinden işlenir; yanıt Türkçe optimizasyonu ve kalite kontrolünden geçer.

Kopyalacurl https://www.numexai.com.tr/api/v1/chat \
  -H "Authorization: Bearer nx_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Python'\''da fibonacci yaz",
    "history": [
      {"role": "user", "content": "Merhaba"},
      {"role": "assistant", "content": "Merhaba! Size nasıl yardımcı olabilirim?"}
    ],
    "maxOutputTokens": 800
  }'

{
  "success": true,
  "answer": "def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)",
  "usage": {
    "estimatedInputTokens": 28,
    "estimatedOutputTokens": 52,
    "estimatedTotalTokens": 80
  }
}

{
  "error": "Yetersiz token bakiyesi",
  "code": "insufficient_tokens",
  "tokenBalance": 0
}

👁️ Vision AKTİF

Görsel analiz endpoint'i. Resim açıklama, OCR, fiş/fatura okuma gibi görevler için numex-vision modelini kullanır.

{
  "success": true,
  "data": { /* modelin döndürdüğü analiz */ },
  "usage": { "billedTokens": 4200 }
}

🧠 Embeddings AKTİF

Metni vektör temsillerine dönüştürür. Semantik arama, benzerlik karşılaştırması ve RAG uygulamaları için kullanılır.

{
  "success": true,
  "embeddings": [[0.0123, -0.0456, ...]],
  "dimensions": 768,
  "count": 1,
  "usage": { "estimatedTokens": 12 }
}

🔍 Web Arama AKTİF

AI destekli web araması yapar ve güncel internet verilerini yanıta dahil eder.

{
  "success": true,
  "query": "Türkiye ekonomisi 2026",
  "sources": [
    { "title": "...", "link": "https://...", "snippet": "..." }
  ],
  "totalResults": 5,
  "usage": { "estimatedTokens": 150 }
}

🤖 Model Listesi AKTİF

Developer API üzerinden erişilebilen modelleri listeler. Chat endpointi model seçimini otomatik yönetir; bu endpoint bilgilendirme amaçlıdır.

⚡ Streaming AKTİF

Chat yanıtlarını SSE (Server-Sent Events) ile parça parça almak için kullanılır.

const response = await fetch('https://www.numexai.com.tr/api/v1/chat/stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nx_live_your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ message: 'Türkiye ekonomisini anlat' })
});
// Yanıt text/event-stream: her satır "data: {...}" — son satır "data: [DONE]"
const reader = response.body.getReader();
// ... okunan chunk'larda { text: "..." } parçaları birleştirilir,
// son event { usage: {...} } toplam kullanılan token bilgisini verir.

🔧 Function Calling AKTİF

Modelin harici araçları çağırmasını sağlar. JSON Schema ile araç tanımları yapılır. Bu özellik /api/v1/chat/agent endpoint'i üzerinden kullanılır (standart /chat endpoint'i tool çağırmaz).

Kopyalacurl https://www.numexai.com.tr/api/v1/chat/agent \
  -H "Authorization: Bearer nx_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "İstanbul'\''da hava nasıl?"}],
    "tools": [
      {
        "name": "hava_durumu",
        "description": "Belirtilen şehrin hava durumunu getirir",
        "input_schema": {
          "type": "object",
          "properties": { "sehir": { "type": "string" } },
          "required": ["sehir"]
        }
      }
    ]
  }'

{
  "success": true,
  "content": [
    { "type": "tool_use", "name": "hava_durumu", "input": { "sehir": "İstanbul" } }
  ],
  "stopReason": "tool_use"
}

📊 Rate Limits

Kullanım düzeyinize göre otomatik yükselen limitler. Tier atlamak için minimum harcama koşulları sağlanmalıdır.

⚠️ Hata Kodları

• 400
  Bad Request

  İstek formatı geçersiz veya zorunlu parametre eksik.
• 401
  Unauthorized

  API anahtarı geçersiz veya eksik. Authorization başlığını kontrol edin.
• 402
  Payment Required — insufficient_tokens

  Token bakiyeniz yetersiz. Yanıt body'sinde "code": "insufficient_tokens" ve mevcut tokenBalance döner. Dashboard'dan token yükleyin.
• 403
  Forbidden

  Bu endpoint'e erişim için planınız yetersiz veya API anahtarınız iptal edilmiş.
• 429
  Too Many Requests

  Rate limit aşıldı. Retry-After başlığına bakın.
• 500
  Internal Server Error

  Sunucu taraflı hata. Lütfen destek ekibine bildirin.
• 503
  Service Unavailable

  Geçici yük sorunu. Exponential backoff ile tekrar deneyin.