> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI API

> Evrensel AI çağrıları — sohbet, görüntüler, konuşma, transkripsiyon, video — alanınıza karşı faturalandırılır.

Kazzle AI API, desteklediğimiz herhangi bir modeli çağırmak için bir kimliği doğrulanmış uç nokta sunar. Bir kez, krediler cinsinden alanınıza karşı ödeme yaparsınız — OpenAI, Anthropic, Cloudflare Workers AI veya yönlendirdiğimiz başka hiçbir hizmet için ayrı hesaplara gerek yoktur.

Tüm uç noktalar `https://api.kazzle.app` üzerinde `/ai/*` altında bulunur ve `Authorization` başlığında `kzl_` API anahtarını kabul eder. Bir anahtar oluşturmak için [API anahtarları](/platform/api-keys) bölümüne bakın.

Oluşturulan Kazzle uygulamaları da bu API'yi kullanmalıdır — anahtarı bir bileşene bağlamak için [Uygulamalarda AI](/apps/ai-api) bölümüne bakın. Kullanıcılardan kendi sağlayıcı hesaplarını açıkça kullanmak istemedikçe sağlayıcı anahtarları istemeyin.

## Yetenekler

| Uç Nokta                        | Modalite             | Standartlaştırılmış Giriş                     | Standartlaştırılmış Çıkış                      |
| ------------------------------- | -------------------- | --------------------------------------------- | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Sohbet (metin, akış) | OpenAI uyumlu `messages[]`                    | OpenAI uyumlu `choices[]` veya SSE akışı       |
| `POST /ai/responses`            | Responses API        | OpenAI Responses uyumlu                       | OpenAI Responses uyumlu                        |
| `POST /ai/images/generations`   | Görüntü              | `{ model, prompt, size?, output_format? }`    | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Metinden konuşmaya   | `{ model, text, voice?, format? }`            | `audio/*` bayt akışı                           |
| `POST /ai/audio/transcriptions` | Konuşmadan metne     | `multipart/form-data` ile `file` + `model`    | `{ text }`                                     |
| `POST /ai/video/generations`    | Video (eşzamansız)   | `{ model, prompt, ... }`                      | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Eşzamansız yoklama   | yanıt id'si                                   | sağlayıcı şeklinde sonuç                       |
| `POST /ai/gateway`              | Ham geçiş            | Herhangi bir Workers AI / sağlayıcı-yerel yük | Ham yukarı akış yanıtı                         |
| `GET  /ai/models`               | Katalog              | —                                             | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models`, hangi model id'lerinin hangi uç noktada çalıştığının kaynağıdır. API'ye karşı oluşturuyorsanız önce bunu okuyun.

## Bir çağrı nasıl çalışır

Her faturalandırılabilir çağrı beş aşamadan geçer. Bunların çoğunu görmezsiniz — sunucu tarafında izlenir, böylece başarısız çağrıları geri ödeyebilir ve tam kullanımı raporlayabiliriz.

| Aşama      | Ne Oldu                                                                                                                       |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `open`     | İsteğinize bağlı bir faturalandırma olayı oluşturduk, ancak henüz yukarı akışı çağırmadık.                                    |
| `recorded` | Yukarı akış sağlayıcısı yanıt verdi. Cloudflare AI Gateway'den bir günlük id'si aldık. Maliyet henüz bilinmiyor.              |
| `priced`   | Cloudflare nihai maliyeti bildirdi. İşaretlememizi uyguladık ve kredi ücretini yazdık. Terminal.                              |
| `failed`   | Yukarı akış çağrısı başarısız oldu veya 20 yeniden denemeden sonra maliyet alamadık. Müşteri **faturalandırılmaz**. Terminal. |
| `synced`   | Fiyatlandırılmış olay ölçüm sistemimize teslim edildi.                                                                        |

Her başarılı yanıt `x-kazzle-ai-billing-event-id: airesp_...` içerir — daha sonra isteği kullanım dışa aktarımlarıyla ilişkilendirmek istiyorsanız saklayın.

## Faturalandırma ve İşaretleme

`cloudflare_cost_usd × (1 + markup)` ücretlendiririz. İşaretleme [Ayarlar → Faturalandırma → Fiyatlandırma](/platform/billing#pricing) bölümünde yayınlanır. Cloudflare'nin \$0 olarak fiyatlandırdığı çağrılar (ücretsiz Workers AI katmanı, promosyonlar) `priced` aşamasına sıfır maliyetle ulaşır ve hiçbir zaman faturalandırılmaz.

Rezerv: bir çağrı yapmak için en az **\$0.50** eşdeğer krediye ihtiyacınız vardır. Bunu bakiyenize karşı tutarız, çağrı bitene kadar, ardından gerçek maliyeti kapatırız.

## Hatalar

| Durum                | Anlamı                                                                               |
| -------------------- | ------------------------------------------------------------------------------------ |
| `401`                | Eksik veya geçersiz `kzl_` API anahtarı.                                             |
| `402`                | Rezerv için yetersiz krediler. **Ayarlar → Faturalandırma** bölümünde doldur.        |
| `4xx` yukarı akıştan | Olduğu gibi iletilir. Gövde sağlayıcının hatasını içerir. Müşteri faturalandırılmaz. |
| `5xx` yukarı akıştan | Olduğu gibi iletilir. Müşteri faturalandırılmaz.                                     |

## Örnek — görüntü oluşturma

```bash theme={"theme":"material-theme-darker"}
curl https://api.kazzle.app/ai/images/generations \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "a single red dot on white",
    "size": "1024x1024"
  }'
```

```json theme={"theme":"material-theme-darker"}
{
  "images": [
    { "url": "https://...", "mimeType": "image/png" }
  ]
}
```

## Örnek — metinden konuşmaya

```bash theme={"theme":"material-theme-darker"}
curl https://api.kazzle.app/ai/audio/speech \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/tts-1","text":"hello world","voice":"alloy","format":"mp3"}' \
  --output speech.mp3
```

## Ayrıca bakın

* [API Referansı](/api-reference) — her uç nokta için tam istek/yanıt şemaları
* [API anahtarları](/platform/api-keys) — `kzl_` anahtarları oluşturma ve kullanma
* [Faturalandırma](/platform/billing) — krediler, planlar ve uyguladığımız işaretleme