Skip to main content
The Kazzle AI API gives you one authenticated endpoint to call any model we support. You pay once, in credits, against your space — no separate accounts for OpenAI, Anthropic, Cloudflare Workers AI, or anyone else we route to. All endpoints live under /ai/* on https://api.kazzle.app and accept a kzl_ API key in the Authorization header. See API keys for how to create one. Generated Kazzle apps should use this API too. Create a Kazzle API key for the app, store it in the vault, wire it as KAZZLE_API_KEY on a process component, and call https://api.kazzle.app/ai/* from that server-side code. Do not ask users for provider keys unless they explicitly want to use their own provider account.

​
Capabilities

EndpointModalityStandardized inputStandardized output
POST /ai/chat/completionsChat (text, streaming)OpenAI-compatible messages[]OpenAI-compatible choices[] or SSE stream
POST /ai/responsesResponses APIOpenAI Responses-compatibleOpenAI Responses-compatible
POST /ai/images/generationsImage{ model, prompt, size?, output_format? }{ images: [{ url? | b64?, mimeType }] }
POST /ai/audio/speechText-to-speech{ model, text, voice?, format? }audio/* byte stream
POST /ai/audio/transcriptionsSpeech-to-textmultipart/form-data with file + model{ text }
POST /ai/video/generationsVideo (async){ model, prompt, ... }{ id, status, pollUrl }
GET /ai/responses/{id}Async pollresponse idprovider-shaped result
POST /ai/gatewayRaw passthroughAny Workers AI / provider-native payloadRaw upstream response
GET /ai/modelsCatalog—{ models: [{ id, modality, pricing, ... }] }
GET /ai/models is the source of truth for which model ids work on which endpoint. Read it first if you’re building against the API.

​
How a call works

Every billable call goes through five phases. You don’t see most of these — they’re tracked server-side so we can refund failed calls and report exact usage.
PhaseWhat happened
openWe’ve created a billing event tied to your request, but haven’t called upstream yet.
recordedThe upstream provider returned. We have a log id from Cloudflare AI Gateway. The cost is not yet known.
pricedCloudflare reported the final cost. We applied our markup and wrote the credit charge. Terminal.
failedThe upstream call failed, or we couldn’t get a cost after 20 retries. Customer is not charged. Terminal.
syncedThe priced event has been delivered to our metering system.
Every successful response includes x-kazzle-ai-billing-event-id: airesp_... — keep it if you want to correlate the request with usage exports later.

​
Billing & markup

We charge cloudflare_cost_usd × (1 + markup). The markup is published in Settings → Billing → Pricing. Calls that Cloudflare priced at $0 (free Workers AI tier, promos) reach the priced phase with zero cost and are never billed. Reserve: you need at least $0.50 equivalent in credits to make a call. We hold this against your balance until the call finishes, then settle the actual cost.

​
Errors

StatusMeaning
401Missing or invalid kzl_ API key.
402Insufficient credits for the reserve. Top up in Settings → Billing.
4xx from upstreamForwarded as-is. Body contains the provider’s error. Customer is not billed.
5xx from upstreamForwarded as-is. Customer is not billed.

​
Example — image generation

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

​
Example — text to speech

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

​
See also

  • API Reference — full request/response schemas for every endpoint
  • API keys — creating and using kzl_ keys
  • Billing — credits, plans, and the markup we apply