> ## 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` with `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에 대해 구축하는 경우 먼저 읽으세요.

## 호출 작동 방식

모든 청구 가능한 호출은 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이고 청구되지 않습니다.

예약: 호출을 하려면 최소 **\$0.50** 상당의 크레딧이 필요합니다. 호출이 완료될 때까지 잔액에 대해 이를 보유한 다음 실제 비용을 정산합니다.

## 오류

| 상태                  | 의미                                             |
| ------------------- | ---------------------------------------------- |
| `401`               | 누락되었거나 유효하지 않은 `kzl_` API 키입니다.                |
| `402`               | 예약을 위한 크레딧이 부족합니다. **설정 → 청구**에서 충전하세요.        |
| `4xx` from upstream | 그대로 전달됩니다. 본문에는 제공자의 오류가 포함됩니다. 고객은 청구되지 않습니다. |
| `5xx` from upstream | 그대로 전달됩니다. 고객은 청구되지 않습니다.                      |

## 예제 — 이미지 생성

```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) — 크레딧, 플랜 및 적용하는 마크업