SDK Rehberi & Örnekler

Numex AI'yi uygulamanıza entegre etmek için ihtiyacınız olan her şey. Resmi SDK'lar, hazır kod örnekleri ve uçtan uca uygulama rehberleri.

🔑 API anahtarınız yoksa ücretsiz API anahtarı alın.

📦 Dil ve Ortam Örnekleri

Aşağıdaki örnekler çalışan REST API kullanır. Resmi pip/npm/go/composer paketleri henüz yayında değildir.

⚡ 5 Dakikada İlk İstek

Kopyalapip install requests

Kopyala# Tarayıcıda fetch() kullanın; Node'da node-fetch veya axios

Kopyala# Go SDK henüz yok; REST ile istek atın (net/http veya aşağıdaki cURL)

Kopyala# .env dosyası veya shell
export NUMEX_API_KEY="nx-your-api-key-here"

Kopyalaimport requests
import os

url = "https://www.numexai.com.tr/api/v1/chat"
headers = {
    "Authorization": "Bearer " + os.environ.get("NUMEX_API_KEY", ""),
    "Content-Type": "application/json"
}
payload = {
    "message": "Merhaba! Bana Türkiye hakkında kısa bir bilgi ver.",
    "history": [],
    "maxOutputTokens": 512
}
r = requests.post(url, json=payload, headers=headers)
print(r.json().get("text", ""))

🐍 Python (REST API)

Python 3.8+ ile requests kütüphanesi kullanarak API çağrısı. Resmi pip install numex paketi henüz yok; aşağıdaki örnek çalışır.

Kurulum

Kopyalapip install requests

Temel Kullanım

Kopyalaimport requests
import os

url = "https://www.numexai.com.tr/api/v1/chat"
headers = {
    "Authorization": "Bearer " + os.environ.get("NUMEX_API_KEY", ""),
    "Content-Type": "application/json"
}
payload = {
    "message": "Python'da quicksort yaz",
    "history": [],
    "maxOutputTokens": 2048
}
r = requests.post(url, json=payload, headers=headers)
data = r.json()
print(data.get("text", ""))
print(f"Token: {data.get('usage', {}).get('total_tokens', 'N/A')}")

Async (aiohttp)

Kopyala# pip install aiohttp
import asyncio
import aiohttp

async def main():
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://www.numexai.com.tr/api/v1/chat",
            headers={"Authorization": "Bearer nx-your-key", "Content-Type": "application/json"},
            json={"message": "Merhaba!", "history": [], "maxOutputTokens": 512}
        ) as resp:
            data = await resp.json()
            print(data.get("text", ""))

asyncio.run(main())

🟨 JavaScript / TypeScript (REST API)

Tarayıcıda fetch, Node.js'te fetch (18+) veya node-fetch. Resmi npm install numex-ai paketi henüz yok; aşağıdaki örnek çalışır.

Kurulum

Kopyala# Tarayıcıda ek paket gerekmez. Node 18+ yerleşik fetch kullanır.
# Node <18 için: npm install node-fetch

Temel Kullanım (fetch)

Kopyalaconst response = await fetch('https://www.numexai.com.tr/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.NUMEX_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Koşullu cümle örnekleri ver',
    history: [],
    maxOutputTokens: 1024
  })
});
const data = await response.json();
console.log(data.text);

Next.js API Route

Kopyala// app/api/chat/route.ts
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { message, history } = await req.json();
  const res = await fetch('https://www.numexai.com.tr/api/v1/chat', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + process.env.NUMEX_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ message, history: history ?? [], maxOutputTokens: 1024 })
  });
  const data = await res.json();
  return NextResponse.json({ content: data.text });
}

🔵 Go (REST API)

Resmi go get numexai.com.tr/go paketi henüz yok. Aşağıdaki örnek standart net/http ve encoding/json ile çalışır.

Kopyalapackage main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    url := "https://www.numexai.com.tr/api/v1/chat"
    body, _ := json.Marshal(map[stringinterface{}]{
        "message": "Go'da HTTP sunucu yaz",
        "history": []interface{}{},
        "maxOutputTokens": 512,
    })
    req, _ := http.NewRequest("POST", url, bytes.NewReader(body))
    req.Header().Set("Authorization", "Bearer "+os.Getenv("NUMEX_API_KEY"))
    req.Header().Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    var out struct { Text string `json:"text"` }
    json.NewDecoder(resp.Body).Decode(&out)
    fmt.Println(out.Text)
}

🐘 PHP (REST API)

Resmi composer require numex/ai paketi henüz Packagist'te yok. Aşağıdaki örnek file_get_contents veya cURL ile çalışır.

Kopyala<?php
$url = 'https://www.numexai.com.tr/api/v1/chat';
$payload = json_encode([
  'message' => 'Merhaba Numex, kısa bir selam ver.',
  'history' => [],
  'maxOutputTokens' => 512
]);
$ctx = stream_context_create([
  'http' => [
    'method' => 'POST',
    'header' => "Authorization: Bearer " . getenv('NUMEX_API_KEY') . "\r\nContent-Type: application/json\r\n",
    'content' => $payload
  ]
]);
$res = file_get_contents($url, false, $ctx);
$data = json_decode($res, true);
echo $data['text'] ?? '';

🌐 REST / cURL

SDK kullanmadan doğrudan HTTP ile çağrı yapmak için cURL örneği:

Kopyalacurl https://www.numexai.com.tr/api/v1/chat \
  -H "Authorization: Bearer nx_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Kısa bir ürün açıklaması yaz","history":[],"maxOutputTokens":512}'

🤖 Örnek: Türkçe Chatbot

Bağlam hafızalı, çok turlu bir chatbot uygulaması. Konuşma geçmişini korur.

Kopyalaimport requests
import os

url = "https://www.numexai.com.tr/api/v1/chat"
headers = {"Authorization": "Bearer " + os.environ.get("NUMEX_API_KEY", ""), "Content-Type": "application/json"}
history = []

def chat(user_message: str) -> str:
    payload = {
        "message": user_message,
        "history": history,
        "maxOutputTokens": 512
    }
    r = requests.post(url, json=payload, headers=headers)
    data = r.json()
    text = data.get("text", "")
    history.append({"role": "user", "content": user_message})
    history.append({"role": "assistant", "content": text})
    return text

# Örnek konuşma (system davranışı ilk mesajda belirtilebilir)
print(chat("Sen FatmaAna'sın, Türk mutfağı uzmanısın. Merhaba! Bugün ne pişirsem?"))
print(chat("Malzemeleri var mı kontrol edeyim, ne lazım?"))
print(chat("Kaç kişilik tarif versene"))

🔍 Örnek: RAG Sistemi

Embedding + Chat API kullanarak belgelerinizden soru yanıtlama (Retrieval-Augmented Generation).

Kopyalaimport requests
import os

# Embedding API yoksa basit anahtar kelime eşleşmesi ile bağlam seç
belgeler = [
    "Numex AI, Türkiye'nin yapay zeka platformudur.",
    "API ile sohbet, görsel ve ses üretimi yapılabilir.",
    "Pro plan aylık 399 TL'dir ve API erişimi içerir."
]

def soru_yanıtla(soru: str) -> str:
    # Basit bağlam: soru kelimeleri geçen ilk belge
    en_iyi = belgeler[0]
    for b in belgeler:
        if any(w in b for w in soru.lower().split()):
            en_iyi = b
            break
    r = requests.post(
        "https://www.numexai.com.tr/api/v1/chat",
        headers={"Authorization": "Bearer "+os.environ.get("NUMEX_API_KEY",""), "Content-Type": "application/json"},
        json={"message": f"Bağlam: {en_iyi}\n\nSoru: {soru}", "history": [], "maxOutputTokens": 256}
    )
    return r.json().get("text", "")

print(soru_yanıtla("Pro plan ne kadara?"))

✍️ Örnek: İçerik Üretimi

Blog, ürün açıklaması ve sosyal medya metinleri için şablonlu içerik üretimi.

Kopyalaimport requests
import os

r = requests.post(
    "https://www.numexai.com.tr/api/v1/chat",
    headers={"Authorization": "Bearer " + os.environ.get("NUMEX_API_KEY", ""), "Content-Type": "application/json"},
    json={
        "message": "Sen bir içerik stratejistisin. Türkçe, net ve satış odaklı yaz. Organik bal için kısa ürün açıklaması yaz. 3 madde + 1 CTA olsun.",
        "history": [],
        "maxOutputTokens": 512
    }
)
print(r.json().get("text", ""))

💻 Örnek: Kod Asistanı

Kod yazdırma, bug düzeltme ve refactor görevleri için `numex-code` profili.

Kopyalaimport requests
import os

url = "https://www.numexai.com.tr/api/v1/chat"
r = requests.post(url,
    headers={"Authorization": "Bearer " + os.environ.get("NUMEX_API_KEY", ""), "Content-Type": "application/json"},
    json={
        "message": "Temiz ve production-ready kod yaz. Express ile /health endpoint yaz ve basit test örneği ekle.",
        "history": [],
        "maxOutputTokens": 1200
    }
)
print(r.json().get("text", ""))

🎙️ Örnek: Sesli Asistan

TTS endpoint ile metni sese çevirip dosya olarak kaydetme örneği.

Kopyalaimport requests

API_KEY = "nx-your-api-key"
url = "https://www.numexai.com.tr/api/v1/audio/speech"

payload = {
  "input": "Merhaba, Numex sesli asistana hoş geldiniz.",
  "voice": "zeynep",
  "format": "mp3"
}

r = requests.post(
  url,
  headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
  json=payload,
  timeout=60
)
r.raise_for_status()
open("numex-tts.mp3", "wb").write(r.content)

💡 Prompt Mühendisliği

Numex AI modellerinden en iyi sonuçları almak için kanıtlanmış teknikler.

"Sen Türk hukuku konusunda uzman bir
avukatsın. Cevaplarında yasal
kaynaklara atıfta bulun."

"Yanıtını JSON formatında ver:
{
  'özet': '...',
  'maddeler': [],
  'sonuç': '...'
}"

"Şirketimiz B2B SaaS satıyor.
Hedef kitle: KOBİ'ler.
Bütçe: Orta.
→ Pazarlama stratejisi öner"

🛡️ Hata Yönetimi

Üretim ortamında sağlıklı çalışma için hata yönetimi ve retry mantığı şarttır.

Kopyalaimport requests
import time
import os

url = "https://www.numexai.com.tr/api/v1/chat"
headers = {"Authorization": "Bearer " + os.environ.get("NUMEX_API_KEY", ""), "Content-Type": "application/json"}

def güvenli_chat(message: str, history=None, max_retries=3):
    for deneme in range(max_retries):
        r = requests.post(url, headers=headers, json={
            "message": message, "history": history or [], "maxOutputTokens": 512
        })
        if r.status_code == 429:
            bekleme = 2 ** deneme
            print(f"Rate limit, {bekleme}s bekleniyor...")
            time.sleep(bekleme)
            continue
        if r.status_code == 401:
            raise ValueError("Geçersiz API anahtarı")
        if r.status_code >= 500 and deneme < max_retries - 1:
            time.sleep(1)
            continue
        r.raise_for_status()
        return r.json().get("text", "")
    raise Exception("Maksimum deneme sayısına ulaşıldı")

✅ Best Practices