AI API

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 — see AI in apps for wiring the key into a component. Do not ask users for provider keys unless they explicitly want to use their own provider account.

Capabilities

Endpoint	Modality	Standardized input	Standardized output
`POST /ai/chat/completions`	Chat (text, streaming)	OpenAI-compatible `messages[]`	OpenAI-compatible `choices[]` or SSE stream
`POST /ai/responses`	Responses API	OpenAI Responses-compatible	OpenAI Responses-compatible
`POST /ai/images/generations`	Image	`{ model, prompt, size?, output_format? }`	`{ images: [{ url? \| b64?, mimeType }] }`
`POST /ai/audio/speech`	Text-to-speech	`{ model, text, voice?, format? }`	`audio/*` byte stream
`POST /ai/audio/transcriptions`	Speech-to-text	`multipart/form-data` with `file` + `model`	`{ text }`
`POST /ai/video/generations`	Video (async)	`{ model, prompt, ... }`	`{ id, status, pollUrl }`
`GET /ai/responses/{id}`	Async poll	response id	provider-shaped result
`POST /ai/gateway`	Raw passthrough	Any Workers AI / provider-native payload	Raw upstream response
`GET /ai/models`	Catalog	—	`{ 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.

Phase	What happened
`open`	We’ve created a billing event tied to your request, but haven’t called upstream yet.
`recorded`	The upstream provider returned. We have a log id from Cloudflare AI Gateway. The cost is not yet known.
`priced`	Cloudflare reported the final cost. We applied our markup and wrote the credit charge. Terminal.
`failed`	The upstream call failed, or we couldn’t get a cost after 20 retries. Customer is not charged. Terminal.
`synced`	The 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

Status	Meaning
`401`	Missing or invalid `kzl_` API key.
`402`	Insufficient credits for the reserve. Top up in Settings → Billing.
`4xx` from upstream	Forwarded as-is. Body contains the provider’s error. Customer is not billed.
`5xx` from upstream	Forwarded 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

About Kazzle

Work

Browse

Code

Apps

Security

Platform

Capabilities

How a call works

Billing & markup

Errors

Example — image generation

Example — text to speech

See also

​Capabilities

​How a call works

​Billing & markup

​Errors

​Example — image generation

​Example — text to speech

​See also

Capabilities

How a call works

Billing & markup

Errors

Example — image generation

Example — text to speech

See also