> ## 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 は、サポートしているあらゆるモデルを呼び出すための 1 つの認証済みエンドポイントを提供します。クレジットでスペースに対して 1 回だけ支払います。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 に対して構築する場合は、最初にこれを読んでください。

## 呼び出しの仕組み

課金対象のすべての呼び出しは 5 つのフェーズを通過します。ほとんどのフェーズは表示されません。失敗した呼び出しを払い戻し、正確な使用状況を報告できるようにサーバー側で追跡されます。

| フェーズ       | 内容                                                                       |
| ---------- | ------------------------------------------------------------------------ |
| `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) — クレジット、プラン、適用するマークアップ