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

> Gọi AI phổ quát — chat, hình ảnh, giọng nói, chuyển đổi giọng nói, video — được tính phí theo không gian của bạn.

Kazzle AI API cung cấp cho bạn một endpoint được xác thực để gọi bất kỳ mô hình nào chúng tôi hỗ trợ. Bạn chỉ trả một lần, bằng credit, theo không gian của bạn — không cần tài khoản riêng cho OpenAI, Anthropic, Cloudflare Workers AI, hoặc bất kỳ ai khác mà chúng tôi định tuyến đến.

Tất cả các endpoint nằm dưới `/ai/*` trên `https://api.kazzle.app` và chấp nhận khóa API `kzl_` trong header `Authorization`. Xem [API keys](/platform/api-keys) để biết cách tạo một khóa.

Các ứng dụng Kazzle được tạo ra cũng nên sử dụng API này — xem [AI in apps](/apps/ai-api) để kết nối khóa vào một thành phần. Không yêu cầu người dùng cung cấp khóa nhà cung cấp trừ khi họ rõ ràng muốn sử dụng tài khoản nhà cung cấp của riêng họ.

## Khả năng

| Endpoint                        | Modality               | Standardized input                          | Standardized output                            |
| ------------------------------- | ---------------------- | ------------------------------------------- | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Chat (text, streaming) | OpenAI-compatible `messages[]`              | OpenAI-compatible `choices[]` or SSE stream    |
| `POST /ai/responses`            | Responses API          | OpenAI Responses-compatible                 | OpenAI Responses-compatible                    |
| `POST /ai/images/generations`   | Image                  | `{ model, prompt, size?, output_format? }`  | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Text-to-speech         | `{ model, text, voice?, format? }`          | `audio/*` byte stream                          |
| `POST /ai/audio/transcriptions` | Speech-to-text         | `multipart/form-data` with `file` + `model` | `{ text }`                                     |
| `POST /ai/video/generations`    | Video (async)          | `{ model, prompt, ... }`                    | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Async poll             | response id                                 | provider-shaped result                         |
| `POST /ai/gateway`              | Raw passthrough        | Any Workers AI / provider-native payload    | Raw upstream response                          |
| `GET  /ai/models`               | Catalog                | —                                           | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` là nguồn sự thật cho biết ID mô hình nào hoạt động trên endpoint nào. Hãy đọc nó trước nếu bạn đang xây dựng dựa trên API.

## Cách một cuộc gọi hoạt động

Mỗi cuộc gọi có thể tính phí đi qua năm giai đoạn. Bạn không thấy hầu hết những giai đoạn này — chúng được theo dõi phía máy chủ để chúng tôi có thể hoàn lại các cuộc gọi không thành công và báo cáo mức sử dụng chính xác.

| Phase      | What happened                                                                                                                            |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `open`     | Chúng tôi đã tạo một sự kiện tính phí được liên kết với yêu cầu của bạn, nhưng chưa gọi upstream.                                        |
| `recorded` | Nhà cung cấp upstream đã trả lời. Chúng tôi có một ID nhật ký từ Cloudflare AI Gateway. Chi phí chưa được biết.                          |
| `priced`   | Cloudflare đã báo cáo chi phí cuối cùng. Chúng tôi đã áp dụng markup của mình và ghi lại khoản phí credit. Terminal.                     |
| `failed`   | Cuộc gọi upstream không thành công, hoặc chúng tôi không thể lấy chi phí sau 20 lần thử lại. Khách hàng **không** bị tính phí. Terminal. |
| `synced`   | Sự kiện được định giá đã được gửi đến hệ thống đo lường của chúng tôi.                                                                   |

Mỗi phản hồi thành công bao gồm `x-kazzle-ai-billing-event-id: airesp_...` — giữ nó nếu bạn muốn tương quan yêu cầu với các bản xuất sử dụng sau này.

## Tính phí & markup

Chúng tôi tính phí `cloudflare_cost_usd × (1 + markup)`. Markup được công bố trong [Settings → Billing → Pricing](/platform/billing#pricing). Các cuộc gọi mà Cloudflare định giá ở \$0 (tầng Workers AI miễn phí, khuyến mãi) đạt giai đoạn `priced` với chi phí bằng không và không bao giờ bị tính phí.

Reserve: bạn cần ít nhất **\$0.50** tương đương trong credit để thực hiện một cuộc gọi. Chúng tôi giữ điều này so với số dư của bạn cho đến khi cuộc gọi kết thúc, sau đó thanh toán chi phí thực tế.

## Lỗi

| Status              | Meaning                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `401`               | Khóa API `kzl_` bị thiếu hoặc không hợp lệ.                                                  |
| `402`               | Credit không đủ cho reserve. Nạp tiền trong **Settings → Billing**.                          |
| `4xx` from upstream | Được chuyển tiếp nguyên trạng. Body chứa lỗi của nhà cung cấp. Khách hàng không bị tính phí. |
| `5xx` from upstream | Được chuyển tiếp nguyên trạng. Khách hàng không bị tính phí.                                 |

## Ví dụ — tạo hình ảnh

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

## Ví dụ — chuyển đổi văn bản thành giọng nói

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

## Xem thêm

* [API Reference](/api-reference) — full request/response schemas cho mỗi endpoint
* [API keys](/platform/api-keys) — tạo và sử dụng khóa `kzl_`
* [Billing](/platform/billing) — credit, gói và markup mà chúng tôi áp dụng