Dokümantasyon

Bağlanma

OpenAI SDK'nızı (ya da curl'ü) aşağıdaki taban URL'ye yönlendirin ve anahtarlarınızdan birini taşıyıcı (bearer) jeton olarak kullanın.

Anahtarınızı hesabınızda Hesap → API Anahtarları üzerinden alın.

curl https://ai-gateway.talivio.com/v1/chat/completions \
  -H "Authorization: Bearer $TALIVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "talivio/standard", "messages": [{"role": "user", "content": "Hello"}]}'

from openai import OpenAI

client = OpenAI(base_url="https://ai-gateway.talivio.com/v1", api_key="TALIVIO_API_KEY")

response = client.chat.completions.create(
    model="talivio/standard",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://ai-gateway.talivio.com/v1", apiKey: "TALIVIO_API_KEY" });

const response = await client.chat.completions.create({
  model: "talivio/standard",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

Kalite katmanları ve ham model kimlikleri

Bir modelin adını bilmenize gerek yok. "model" alanına sanal bir kalite katmanı adı yazın (ör. "talivio/standard"), ağ geçidi o kalite için en uygun modeli seçer. Anahtarınız ham modele izin veriyorsa "GET /v1/models" ayrıca "provider/model_id" biçiminde sağlayıcıya özel kimlikleri de kendi "pricing" bloğuyla listeler.

Kullanılabilir katmanlar:

• talivio/cheap
• talivio/standard
• talivio/smart
• talivio/cheap-eu
• talivio/very-smart

Akış (streaming)

"stream": true verirseniz OpenAI-uyumlu bir Server-Sent Events akışı alırsınız. Son parça, aşağıdaki "usage.talivio" ayrıntılarını içeren "usage" bloğunu taşır.

curl https://ai-gateway.talivio.com/v1/chat/completions \
  -H "Authorization: Bearer $TALIVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "talivio/standard", "stream": true, "messages": [{"role": "user", "content": "Hello"}]}'

Araçlar (tools)

Fonksiyon/araç tanımları doğrudan modele iletilir. Ağ geçidi asla bir aracı kendisi çalıştırmaz — yalnızca modelin bir aracı çağırma NİYETİNİ (yanıttaki "tool_calls") size iletir. Aracı çalıştırmak ve sonucunu geri göndermek uygulamanızın işidir.

usage.talivio bloğu

Her yanıt (akışlı ya da değil), standart token sayılarının yanında bir "usage.talivio" nesnesi taşır; böylece isteğinizi kimin karşıladığını ve maliyetini her zaman tam olarak bilirsiniz.

{
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 128,
    "total_tokens": 170,
    "talivio": {
      "request_id": "req_...",
      "provider": "openai",
      "model": "gpt-5-mini",
      "requested_tier": "standard",
      "resolved_tier": "standard",
      "degraded": false,
      "failover_used": false,
      "local": false,
      "cached_tokens": 0,
      "reasoning_tokens": 0,
      "cost_eur": 0.00041231,
      "fx_stale": false,
      "latency_ms": 812
    }
  }
}

Hesap uçları

Üç salt okunur uç, kendi arka ucunuzdan çıkmadan kullanım ve faturalamayı izlemenizi sağlar.

• • "GET /v1/usage" — projenizin kullanım kayıtları.
• • "GET /v1/billing/balance" — tahsil edilmemiş bakiyeniz, kredi tavanınız ve hesap durumunuz.
• • "GET /v1/billing/invoices" — günlük tahsilatlarınız.

Oran sınırları

Her yanıt "X-RateLimit-Limit" ve "X-RateLimit-Remaining" başlıklarını taşır. Sınırlandığınızda "Retry-After" başlığıyla HTTP 429 alırsınız — o süre dolmadan tekrar denemeyin.

Idempotency

Aynı isteği (ör. zaman aşımı sonrası bir tekrar deneme) aynı "X-Talivio-Idempotency-Key" başlığıyla iki kez gönderirseniz ağ geçidi onu iki kez ücretlendirmez ya da çalıştırmaz.

X-Talivio-Idempotency-Key: 5f4e...