Saltar al contenido principal
La API de IA de Kazzle te proporciona 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. Crea una clave API de Kazzle para la app, guárdala en el vault, configúrala como KAZZLE_API_KEY en un componente de proceso, y llama a https://api.kazzle.app/ai/* desde ese código del lado del servidor. No pidas a los usuarios claves de proveedores a menos que explícitamente quieran usar su propia cuenta de proveedor.

​
Capacidades

EndpointModalidadEntrada estandarizadaSalida estandarizada
POST /ai/chat/completionsChat (texto, streaming)messages[] compatible con OpenAIchoices[] compatible con OpenAI o stream SSE
POST /ai/responsesAPI de RespuestasCompatible con Respuestas de OpenAICompatible con Respuestas de OpenAI
POST /ai/images/generationsImagen{ model, prompt, size?, output_format? }{ images: [{ url? | b64?, mimeType }] }
POST /ai/audio/speechSíntesis de voz{ model, text, voice?, format? }stream de bytes audio/*
POST /ai/audio/transcriptionsReconocimiento de vozmultipart/form-data con file + model{ text }
POST /ai/video/generationsVídeo (asincrónico){ model, prompt, ... }{ id, status, pollUrl }
GET /ai/responses/{id}Sondeo asincrónicoid de respuestaresultado con forma de proveedor
POST /ai/gatewayPaso directoCualquier payload nativo de Workers AI / proveedorRespuesta upstream sin procesar
GET /ai/modelsCatálogo—{ models: [{ id, modality, pricing, ... }] }
GET /ai/models es la fuente de verdad sobre qué ids de modelo funcionan en qué 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 del lado del servidor para que podamos reembolsar llamadas fallidas e informar el uso exacto.
FaseQué sucedió
openHemos creado un evento de facturación vinculado a tu solicitud, pero aún no hemos llamado al proveedor.
recordedEl proveedor upstream respondió. Tenemos un id de log de Cloudflare AI Gateway. El costo aún no se conoce.
pricedCloudflare reportó el costo final. Aplicamos nuestro margen y registramos el cargo de crédito. Terminal.
failedLa llamada upstream falló, o no pudimos obtener un costo después de 20 reintentos. El cliente no es facturado. Terminal.
syncedEl 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) alcanzan la fase priced con costo cero 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

EstadoSignificado
401Clave API kzl_ faltante o inválida.
402Créditos insuficientes para la reserva. Recarga en Configuración → Facturación.
4xx desde upstreamReenviado tal cual. El cuerpo contiene el error del proveedor. El cliente no es facturado.
5xx desde upstreamReenviado 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

​
Ver también