API de IA

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 para saber cómo crear una. Las apps de Kazzle generadas también deben usar esta API — consulta IA en apps 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. 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

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"
  }'

{
  "images": [
    { "url": "https://...", "mimeType": "image/png" }
  ]
}

Ejemplo — síntesis de voz

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 — esquemas completos de solicitud/respuesta para cada endpoint
Claves API — crear y usar claves kzl_
Facturación — créditos, planes y el margen que aplicamos

Acerca de Kazzle

Trabajo

Navegar

Código

Apps

Seguridad

Plataforma

Capacidades

Cómo funciona una llamada

Facturación y margen

Errores

Ejemplo — generación de imágenes

Ejemplo — síntesis de voz

Véase también

​Capacidades

​Cómo funciona una llamada

​Facturación y margen

​Errores

​Ejemplo — generación de imágenes

​Ejemplo — síntesis de voz

​Véase también

Capacidades

Cómo funciona una llamada

Facturación y margen

Errores

Ejemplo — generación de imágenes

Ejemplo — síntesis de voz

Véase también