🚀 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) ve numex-audio (ses) 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
}

🎙️ 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 YAKINDA

Developer API üzerinden erişilebilen modelleri listeler. Chat endpointi model seçimini otomatik yönetir; bu endpoint bilgilendirme amaçlıdır. Liste endpoint'i yakında aktif olacaktı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://www.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.