> ## 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

> Panggilan AI universal — chat, gambar, ucapan, transkripsi, video — ditagih terhadap space Anda.

Kazzle AI API memberi Anda satu endpoint terautentikasi untuk memanggil model apa pun yang kami dukung. Anda membayar sekali, dalam kredit, terhadap space Anda — tanpa akun terpisah untuk OpenAI, Anthropic, Cloudflare Workers AI, atau siapa pun yang kami arahkan.

Semua endpoint berada di bawah `/ai/*` pada `https://api.kazzle.app` dan menerima kunci API `kzl_` di header `Authorization`. Lihat [Kunci API](/platform/api-keys) untuk cara membuat satu.

Aplikasi Kazzle yang dihasilkan juga harus menggunakan API ini — lihat [AI dalam aplikasi](/apps/ai-api) untuk menghubungkan kunci ke komponen. Jangan minta pengguna untuk kunci penyedia kecuali mereka secara eksplisit ingin menggunakan akun penyedia mereka sendiri.

## Kemampuan

| Endpoint                        | Modalitas              | Input Standar                                 | Output Standar                                 |
| ------------------------------- | ---------------------- | --------------------------------------------- | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Chat (teks, streaming) | `messages[]` kompatibel OpenAI                | `choices[]` kompatibel OpenAI atau aliran SSE  |
| `POST /ai/responses`            | Responses API          | Kompatibel OpenAI Responses                   | Kompatibel OpenAI Responses                    |
| `POST /ai/images/generations`   | Gambar                 | `{ model, prompt, size?, output_format? }`    | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Text-to-speech         | `{ model, text, voice?, format? }`            | aliran byte `audio/*`                          |
| `POST /ai/audio/transcriptions` | Speech-to-text         | `multipart/form-data` dengan `file` + `model` | `{ text }`                                     |
| `POST /ai/video/generations`    | Video (async)          | `{ model, prompt, ... }`                      | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Polling async          | id respons                                    | hasil berbentuk penyedia                       |
| `POST /ai/gateway`              | Passthrough mentah     | Payload native Workers AI / penyedia apa pun  | Respons upstream mentah                        |
| `GET  /ai/models`               | Katalog                | —                                             | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` adalah sumber kebenaran untuk id model mana yang bekerja di endpoint mana. Bacalah terlebih dahulu jika Anda membangun terhadap API.

## Cara panggilan bekerja

Setiap panggilan yang dapat ditagih melalui lima fase. Anda tidak melihat sebagian besar — mereka dilacak di sisi server sehingga kami dapat mengembalikan panggilan yang gagal dan melaporkan penggunaan yang tepat.

| Fase       | Apa yang terjadi                                                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `open`     | Kami telah membuat acara penagihan yang terikat pada permintaan Anda, tetapi belum memanggil upstream.                              |
| `recorded` | Penyedia upstream mengembalikan. Kami memiliki id log dari Cloudflare AI Gateway. Biayanya belum diketahui.                         |
| `priced`   | Cloudflare melaporkan biaya akhir. Kami menerapkan markup kami dan menulis tagihan kredit. Terminal.                                |
| `failed`   | Panggilan upstream gagal, atau kami tidak bisa mendapatkan biaya setelah 20 percobaan ulang. Pelanggan **tidak** ditagih. Terminal. |
| `synced`   | Acara yang dihargai telah dikirimkan ke sistem metering kami.                                                                       |

Setiap respons yang berhasil mencakup `x-kazzle-ai-billing-event-id: airesp_...` — simpan jika Anda ingin menghubungkan permintaan dengan ekspor penggunaan nanti.

## Penagihan & markup

Kami menagih `cloudflare_cost_usd × (1 + markup)`. Markup dipublikasikan di [Settings → Billing → Pricing](/platform/billing#pricing). Panggilan yang Cloudflare hargai pada \$0 (tingkat Workers AI gratis, promosi) mencapai fase `priced` dengan biaya nol dan tidak pernah ditagih.

Cadangan: Anda memerlukan setidaknya **\$0,50** setara dalam kredit untuk melakukan panggilan. Kami menahan ini terhadap saldo Anda sampai panggilan selesai, kemudian menyelesaikan biaya sebenarnya.

## Kesalahan

| Status              | Arti                                                                             |
| ------------------- | -------------------------------------------------------------------------------- |
| `401`               | Kunci API `kzl_` hilang atau tidak valid.                                        |
| `402`               | Kredit tidak cukup untuk cadangan. Isi ulang di **Settings → Billing**.          |
| `4xx` dari upstream | Diteruskan apa adanya. Badan berisi kesalahan penyedia. Pelanggan tidak ditagih. |
| `5xx` dari upstream | Diteruskan apa adanya. Pelanggan tidak ditagih.                                  |

## Contoh — pembuatan gambar

```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" }
  ]
}
```

## Contoh — text to speech

```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
```

## Lihat juga

* [Referensi API](/api-reference) — skema permintaan/respons lengkap untuk setiap endpoint
* [Kunci API](/platform/api-keys) — membuat dan menggunakan kunci `kzl_`
* [Penagihan](/platform/billing) — kredit, paket, dan markup yang kami terapkan