> ## 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}`       | 异步轮询          | 响应 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) — 积分、计划和我们应用的加价