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://numexai.com.tr/api/v1

🤖 Modeller

Her görev için optimize edilmiş 6 farklı model mevcuttur. Model seçimi, kalite, hız ve maliyet dengesini doğrudan 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://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
}

🎙️ Text-to-Speech YAKINDA

Metni doğal Türkçe sese dönüştürür. Bu endpoint şu an geliştirme aşamasındadır.

🧠 Embeddings YAKINDA

Metni vektör temsillerine dönüştürür. Semantik arama, benzerlik karşılaştırması ve RAG uygulamaları için kullanılır. Bu endpoint şu an geliştirme aşamasındadır.

🎤 Speech-to-Text YAKINDA

Ses dosyasını metne dönüştürür (konuşma tanıma). Türkçe için optimize edilmiş modeller planlanmaktadır.

📄 Belge Analizi YAKINDA

PDF, Word, Excel gibi belgeleri AI ile analiz eder, özetler ve sorgulanabilir hale getirir.

🔍 Web Arama YAKINDA

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

🤖 Model Listesi

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

⚡ Streaming YAKINDA

Streaming (SSE — Server-Sent Events) desteği Developer API için geliştirilmektedir. Şu an yanıtlar tam olarak döner.

const response = await fetch('https://numexai.com.tr/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nx_live_your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ message: 'Türkiye ekonomisini anlat' })
});
// Şu an: tek seferde JSON yanıt
const data = await response.json();
console.log(data.answer);

🔧 Function Calling YAKINDA

Modelin harici araçları ve API'leri çağırmasını sağlar. JSON Schema ile araç tanımları yapılır. Bu özellik Developer API'de henüz aktif değildir.

Kopyalatools = [
    {
        "type": "function",
        "function": {
            "name": "hava_durumu",
            "description": "Belirtilen şehrin hava durumunu getirir",
            "parameters": {
                "type": "object",
                "properties": {
                    "sehir": {"type": "string", "description": "Şehir adı"}
                },
                "required": ["sehir"]
            }
        }
    }
]

response = client.chat.create(
    model="numex-pro",
    messages=[{"role": "user", "content": "İstanbul'da hava nasıl?"}],
    tools=tools,
    tool_choice="auto"
)

📊 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.