Kernlift

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

ConceptWhat it isExample
Provider (a channel)One upstream API account: base URL, API key, request templates, how results come back and how responses are parsedopenai
Provider sceneOne concrete model or endpoint under a provider, with its own request overrides and pricegpt-4o-mini on the OpenAI protocol
SceneWhat your product asks for by code, with an output type, routed to one provider scenechat, 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:

ModeCharges byTypical use
fixedA cost per callOne image at a fixed size
rulesRequest parameters, as combinations or numeric stepsImage size, video duration
tokensToken usage, one total rate or separate input and output ratesText 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

  1. A task starts from a server function or POST /api/<scene>/generate, subject to the ai.tasks.create rate limit. Without a scene, the task type picks one.
  2. The scene, its routed channel and the active provider scene for the media type are resolved, and the price in credits is computed.
  3. The request URL, headers and body are rendered from the templates.
  4. The price is reserved in the credits ledger, and the task is stored as queued with a snapshot of the channel, the price and the masked request.
  5. The provider is called and the response is read with the channel's parser and status mapping.
  6. The outcome settles the reservation:
Provider statusTaskCreditsAlso
SucceededsucceededCapturedOutput URLs are copied into the user's /generated storage folder; a pass safety report is written
FailedfailedRefundedA warn safety report is written
Queued or runningrunningStill reservedWaits 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.

ModeHow the result arrives
syncIn the response to the call. Text is always sync
pollingThe 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
webhookThe 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

  1. POST /api/chat accepts AI SDK UI messages and streams a reply with text and reasoning parts.
  2. The conversation and the user message are stored.
  3. The price is resolved, an estimate is reserved, and the model runs through the provider scene's protocol.
  4. 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.
ProtocolNotes
openaiOpenAI-compatible chat completions. The API key is the bearer token in the provider's request headers
geminiGoogle Generative AI. The key comes from x-goog-api-key, x-api-key or a bearer token
edge_inferenceCloudflare Workers AI through the AI binding; unavailable without the binding
image_generationTasks 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_KEY in 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 /setup shows AI channels as not ready.

Files

src/server/services/ai-workspace.service.ts
src/server/db/repositories/ai-workspace.repository.ts
src/routes/{-$locale}/admin/config/ai.tsx
src/components/ai/admin-ai-operations-workspace.tsx

Next steps