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

# API de IA

> Llamadas universales de IA — chat, imágenes, voz, transcripción, vídeo — facturadas contra tu espacio.

La API de IA de Kazzle te ofrece un único endpoint autenticado para llamar a cualquier modelo que soportamos. Pagas una sola vez, en créditos, contra tu espacio — sin cuentas separadas en OpenAI, Anthropic, Cloudflare Workers AI, ni en ningún otro proveedor al que enrutemos.

Todos los endpoints están bajo `/ai/*` en `https://api.kazzle.app` y aceptan una clave API `kzl_` en el header `Authorization`. Consulta [Claves API](/platform/api-keys) para saber cómo crear una.

Las apps de Kazzle generadas también deben usar esta API — consulta [IA en apps](/apps/ai-api) para conectar la clave en un componente. No pidas a los usuarios claves de proveedor a menos que explícitamente quieran usar su propia cuenta de proveedor.

## Capacidades

| Endpoint                        | Modalidad               | Entrada estandarizada                              | Salida estandarizada                           |
| ------------------------------- | ----------------------- | -------------------------------------------------- | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Chat (texto, streaming) | `messages[]` compatible con OpenAI                 | `choices[]` compatible con OpenAI o stream SSE |
| `POST /ai/responses`            | API de respuestas       | Compatible con Responses de OpenAI                 | Compatible con Responses de OpenAI             |
| `POST /ai/images/generations`   | Imagen                  | `{ model, prompt, size?, output_format? }`         | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Síntesis de voz         | `{ model, text, voice?, format? }`                 | stream de bytes `audio/*`                      |
| `POST /ai/audio/transcriptions` | Reconocimiento de voz   | `multipart/form-data` con `file` + `model`         | `{ text }`                                     |
| `POST /ai/video/generations`    | Vídeo (asincrónico)     | `{ model, prompt, ... }`                           | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Sondeo asincrónico      | id de respuesta                                    | resultado con forma de proveedor               |
| `POST /ai/gateway`              | Paso directo            | Cualquier payload nativo de Workers AI / proveedor | Respuesta upstream sin procesar                |
| `GET  /ai/models`               | Catálogo                | —                                                  | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` es la fuente de verdad sobre qué ids de modelo funcionan en cada endpoint. Consúltalo primero si estás construyendo contra la API.

## Cómo funciona una llamada

Cada llamada facturable pasa por cinco fases. No ves la mayoría — se rastrean en el servidor para que podamos reembolsar llamadas fallidas e informar el uso exacto.

| Fase       | Qué sucedió                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `open`     | Hemos creado un evento de facturación vinculado a tu solicitud, pero aún no hemos llamado al proveedor.                      |
| `recorded` | El proveedor upstream respondió. Tenemos un id de log de Cloudflare AI Gateway. El costo aún no se conoce.                   |
| `priced`   | Cloudflare reportó el costo final. Aplicamos nuestro margen y registramos el cargo de crédito. Terminal.                     |
| `failed`   | La llamada upstream falló, o no pudimos obtener un costo después de 20 reintentos. El cliente **no** es facturado. Terminal. |
| `synced`   | El evento facturado ha sido entregado a nuestro sistema de medición.                                                         |

Cada respuesta exitosa incluye `x-kazzle-ai-billing-event-id: airesp_...` — guárdalo si quieres correlacionar la solicitud con exportaciones de uso más tarde.

## Facturación y margen

Cobramos `cloudflare_cost_usd × (1 + markup)`. El margen se publica en [Configuración → Facturación → Precios](/platform/billing#pricing). Las llamadas que Cloudflare facturó a \$0 (nivel gratuito de Workers AI, promociones) llegan a la fase `priced` sin costo y nunca se facturan.

Reserva: necesitas al menos **\$0.50** equivalente en créditos para hacer una llamada. Retenemos esto contra tu saldo hasta que la llamada termine, luego liquidamos el costo real.

## Errores

| Estado               | Significado                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `401`                | Clave API `kzl_` faltante o inválida.                                                      |
| `402`                | Créditos insuficientes para la reserva. Recarga en **Configuración → Facturación**.        |
| `4xx` desde upstream | Reenviado tal cual. El cuerpo contiene el error del proveedor. El cliente no es facturado. |
| `5xx` desde upstream | Reenviado tal cual. El cliente no es facturado.                                            |

## Ejemplo — generación de imágenes

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

## Ejemplo — síntesis de voz

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

## Véase también

* [Referencia de API](/api-reference) — esquemas completos de solicitud/respuesta para cada endpoint
* [Claves API](/platform/api-keys) — crear y usar claves `kzl_`
* [Facturación](/platform/billing) — créditos, planes y el margen que aplicamos