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

> 通用 AI 呼叫 — 聊天、圖像、語音、轉錄、影片 — 按您的空間計費。

Kazzle AI API 為您提供一個經過身份驗證的端點來呼叫我們支援的任何模型。您只需支付一次信用額度，針對您的空間 — 無需為 OpenAI、Anthropic、Cloudflare Workers AI 或我們路由到的任何其他服務建立單獨帳戶。

所有端點都位於 `https://api.kazzle.app` 的 `/ai/*` 下，並在 `Authorization` 標頭中接受 `kzl_` API 金鑰。請參閱 [API 金鑰](/platform/api-keys) 了解如何建立金鑰。

生成的 Kazzle 應用也應使用此 API — 請參閱 [應用中的 AI](/apps/ai-api) 了解如何將金鑰連接到元件。除非使用者明確想要使用自己的提供者帳戶，否則不要要求他們提供提供者金鑰。

## 功能

| 端點                              | 模式            | 標準化輸入                                      | 標準化輸出                                          |
| ------------------------------- | ------------- | ------------------------------------------ | ---------------------------------------------- |
| `POST /ai/chat/completions`     | 聊天（文字、串流）     | OpenAI 相容 `messages[]`                     | OpenAI 相容 `choices[]` 或 SSE 串流                 |
| `POST /ai/responses`            | Responses API | OpenAI Responses 相容                        | OpenAI Responses 相容                            |
| `POST /ai/images/generations`   | 圖像            | `{ model, prompt, size?, output_format? }` | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | 文字轉語音         | `{ model, text, voice?, format? }`         | `audio/*` 位元組串流                                |
| `POST /ai/audio/transcriptions` | 語音轉文字         | `multipart/form-data` 含 `file` + `model`   | `{ text }`                                     |
| `POST /ai/video/generations`    | 影片（非同步）       | `{ model, prompt, ... }`                   | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | 非同步輪詢         | response id                                | 提供者格式結果                                        |
| `POST /ai/gateway`              | 原始傳遞          | 任何 Workers AI / 提供者原生承載                    | 原始上游回應                                         |
| `GET  /ai/models`               | 目錄            | —                                          | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` 是哪些模型 ID 適用於哪些端點的真實來源。如果您針對 API 進行構建，請先閱讀它。

## 呼叫如何運作

每個可計費呼叫都經過五個階段。您看不到大多數階段 — 它們在伺服器端進行追蹤，以便我們可以退款失敗的呼叫並報告確切的使用情況。

| 階段         | 發生的情況                                               |
| ---------- | --------------------------------------------------- |
| `open`     | 我們已建立與您的請求相關的計費事件，但尚未呼叫上游。                          |
| `recorded` | 上游提供者已回應。我們有來自 Cloudflare AI Gateway 的日誌 ID。成本尚未確定。 |
| `priced`   | Cloudflare 報告了最終成本。我們應用了標記並寫入了信用額度扣費。終端。            |
| `failed`   | 上游呼叫失敗，或我們在 20 次重試後無法獲得成本。客戶**不會**被扣費。終端。           |
| `synced`   | 定價事件已傳遞到我們的計量系統。                                    |

每個成功的回應都包含 `x-kazzle-ai-billing-event-id: airesp_...` — 如果您想稍後將請求與使用情況匯出相關聯，請保留它。

## 計費與標記

我們收費 `cloudflare_cost_usd × (1 + markup)`。標記發佈在 [設定 → 計費 → 定價](/platform/billing#pricing)。Cloudflare 定價為 \$0 的呼叫（免費 Workers AI 層級、促銷）以零成本達到 `priced` 階段，永遠不會被計費。

預留：您需要至少 **\$0.50** 等值的信用額度才能進行呼叫。我們在您的餘額中保留此金額，直到呼叫完成，然後結算實際成本。

## 錯誤

| 狀態         | 含義                          |
| ---------- | --------------------------- |
| `401`      | 遺失或無效的 `kzl_` API 金鑰。       |
| `402`      | 預留信用額度不足。在 **設定 → 計費** 中充值。 |
| `4xx` 來自上游 | 按原樣轉發。正文包含提供者的錯誤。客戶不會被計費。   |
| `5xx` 來自上游 | 按原樣轉發。客戶不會被計費。              |

## 範例 — 圖像生成

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

## 範例 — 文字轉語音

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

## 另請參閱

* [API 參考](/api-reference) — 每個端點的完整請求/回應架構
* [API 金鑰](/platform/api-keys) — 建立和使用 `kzl_` 金鑰
* [計費](/platform/billing) — 信用額度、方案和我們應用的標記