AI channels, scenes and task lifecycle
How providers, provider scenes and scenes fit together, how a price in credits is resolved, and how tasks and chat run from request to settlement.
AI in Kernlift is set up through configuration. You describe upstream APIs in the admin console, expose named scenes to your product, and every call is priced in credits and settled against the ledger. To set it up, see Connect an AI provider and Route scenes and set pricing.
Three layers of configuration
| Concept | What it is | Example |
|---|---|---|
| Provider (a channel) | One upstream API account: base URL, API key, request templates, how results come back and how responses are parsed | openai |
| Provider scene | One concrete model or endpoint under a provider, with its own request overrides and price | gpt-4o-mini on the OpenAI protocol |
| Scene | What your product asks for by code, with an output type, routed to one provider scene | chat, image-creation |
Callers name only a scene. Because a scene routes to one provider scene, you can switch the
model behind image-creation without changing any caller. Chat uses the scene chat unless the
request names another, and tasks are started at POST /api/<scene>/generate.
A scene can only route to an active, ready provider scene with the same output type: text, image,
video or audio. A provider scene is not ready while it lacks an endpoint, pricing, a protocol and
model ID, a polling URL or a webhook secret, whichever its settings need.
How a price is resolved
Each provider scene has a pricing mode:
| Mode | Charges by | Typical use |
|---|---|---|
fixed | A cost per call | One image at a fixed size |
rules | Request parameters, as combinations or numeric steps | Image size, video duration |
tokens | Token usage, one total rate or separate input and output rates | Text models and chat |
Costs are entered in your currency and converted to credits with the credit unit price. The price a user pays is the cost in credits raised by the markup, rounded up, and never less than the cost. The markup comes from the provider scene, otherwise the provider, otherwise the default rules.
Conversion happens when a provider scene is saved, and the result is stored. Changing the credit unit price later does not reprice existing provider scenes until each one is saved again.
How a task runs
- A task starts from a server function or
POST /api/<scene>/generate, subject to theai.tasks.createrate limit. Without a scene, the task type picks one. - The scene, its routed channel and the active provider scene for the media type are resolved, and the price in credits is computed.
- The request URL, headers and body are rendered from the templates.
- The price is reserved in the credits ledger, and the task is stored as
queuedwith a snapshot of the channel, the price and the masked request. - The provider is called and the response is read with the channel's parser and status mapping.
- The outcome settles the reservation:
| Provider status | Task | Credits | Also |
|---|---|---|---|
| Succeeded | succeeded | Captured | Output URLs are copied into the user's /generated storage folder; a pass safety report is written |
| Failed | failed | Refunded | A warn safety report is written |
| Queued or running | running | Still reserved | Waits for a webhook or a poll |
Every state change appends an event to the task's timeline. A user can read only their own tasks. The admin console shows all of them.
Result modes
Image, video and audio providers often finish later, so each channel chooses how results arrive.
| Mode | How the result arrives |
|---|---|
sync | In the response to the call. Text is always sync |
polling | The status URL is queried when a client reads the task through GET /api/status and the polling interval has passed. There is no background timer |
webhook | The provider, or a relay in front of it, posts to /api/ai/channels/webhook/<provider code> |
The schema also accepts webhook_or_polling, but the admin form offers only direct response, status
polling and webhook push.
A webhook must name the task and carry an x-ai-signature header: the hex HMAC-SHA256 of the raw body,
keyed with the channel's webhook secret. Most providers do not sign this way, so a small relay that
checks the provider's own signature and re-signs is the usual setup. A callback for a channel or scene
that does not match the task is rejected. Setup is in Receive async results.
How chat runs
POST /api/chataccepts AI SDK UI messages and streams a reply with text and reasoning parts.- The conversation and the user message are stored.
- The price is resolved, an estimate is reserved, and the model runs through the provider scene's protocol.
- When the stream ends, credits are re-priced from reported token usage and captured. On error the
reservation is refunded and the assistant message is saved with status
error.
| Protocol | Notes |
|---|---|
openai | OpenAI-compatible chat completions. The API key is the bearer token in the provider's request headers |
gemini | Google Generative AI. The key comes from x-goog-api-key, x-api-key or a bearer token |
edge_inference | Cloudflare Workers AI through the AI binding; unavailable without the binding |
image_generation | Tasks only; rejected on the chat path |
Tasks call the rendered request URL directly, so protocol and model ID only drive chat.
Why it is built this way
- No code per provider. Any HTTP API that returns JSON can be described with templates, JSON paths and a status mapping. Only a new chat protocol needs code.
- No environment keys. Keys such as
OPENAI_API_KEYin the environment are ignored. Only the key saved on the provider is used. - Nothing runs unconfigured. The template ships with no providers or scenes. Until a scene routes to
a ready provider scene, tasks fail with a not-available error, no credits are taken and
/setupshows AI channels as not ready.