Kernlift

Route scenes and set pricing

Your product exposes named AI scenes such as chat or image-creation, each routed to a model and priced in credits.

Callers request a scene by its code. Each scene routes to one provider scene, so you can swap the model behind it without changing callers. Every call is priced in credits. The credits are held before the provider is called, then charged on success or returned on failure.

Before you begin

Confirm the provider's billing unit

Check the exact model ID, currency and billing unit in the provider console or current price list before pricing the scene. Text models often separate input and output tokens. Image and video models may charge per request, size or duration. Consult OpenAI pricing, Gemini pricing or Workers AI pricing. For a compatible HTTP service, use its own contract or price list. This application does not sync provider prices. Convert the current price to the Provider scene cost or token rates below, add your markup, then compare one real test request with the provider bill and the credits charged here. The example numbers below are not current provider prices.

Set the credit price

Open Default rules

Go to Settings → AI Config (/admin/config/ai) and open Default rules.

Fill in the global defaults

Under Global defaults, fill in 1 credit price (what one credit is worth, for example 0.01), Markup in percent (for example 50) and Currency (for example USD), then click Save.

Price a provider scene

Open the provider scene

Open Providers, click Provider scenes on the provider's row, and open the model with Configure provider scene.

Choose a pricing mode

Under Provider scene pricing, choose a Pricing mode:

  • Fixed credits: enter Provider scene cost (in your currency) for one call, and optionally Provider scene markup (optional). The preview shows Cost credits and Final charge.
  • Parameter rules: charge by request parameters such as size or duration. With Parameter combinations, add each parameter's Parameter name, Default value and Allowed values. One price row is generated per combination, prefilled from Default cost and Default markup. With Numeric step, set Step parameter, Step size, Cost per step and Minimum steps.
  • Token conversion: for text models. Choose Use one total-token rate and enter Total tokens per currency unit, or Input / output rates and enter both. Chat holds an estimate while the reply streams, then charges for the tokens the model reports.

Save

Click Save. /admin/ai/pricing lists the resulting price of every provider scene.

The charge 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 Default rules. With 1 credit price 0.01:

  • A fixed cost of 0.04 is 4 cost credits. With a 50% markup the user pays 6 credits.
  • A rate of 1000000 total tokens per currency unit makes 10,000 tokens one cost credit. A 25,000-token reply is 3 cost credits, or 5 credits with a 50% markup.

Changing the credit price

Costs are converted to credits with the credit price at the moment you save a provider scene, and the result is stored. If you later change 1 credit price, open each provider scene and save it again, or users keep paying the old amount.

Create a scene and route it

Add the scene

Open Scene routing and click Add scene. Fill in Display name, Code (for example chat or image-creation), Output type, Sort and Status, then click Save.

Pick the model

In the scene's row, pick a model from the Provider scene dropdown. Only active, ready provider scenes with the same output type are listed. If none is ready, click Create a provider scene first. The scene is routed when you save that form.

The badge changes to Active route. Chat uses the scene with code chat unless the request names another. Tasks call POST /api/<code>/generate, for example /api/image-creation/generate.

Verify

Send a chat message

Sign in as the test user on your site and run this in the browser console:

await fetch("/api/chat", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    messages: [{ id: "m1", role: "user", parts: [{ type: "text", text: "Hello" }] }],
  }),
}).then((response) => response.text());

The reply streams back, and the conversation appears under Platform → Chats (/admin/chats).

Run a task

Call a task scene with an API key that has Run AI tasks:

curl -X POST https://your-domain.example/api/image-creation/generate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A ceramic mug on a wooden desk","mediaType":"image","size":"1024x1024"}'

The response includes taskId, status and estimatedPriceCredits. Fields other than reserved names such as prompt, input and mediaType are passed to pricing rules as metadata, so size above can drive a Parameter rules price.

Check the result

  • The user's /app/ai lists the task, and its detail page shows the credits held, charged or returned.
  • Platform → AI Tasks (/admin/ai) shows the task. Failures are listed at /admin/ai/failed with the provider's error.
  • /setup reports AI channels as ready.

pnpm validate:ai runs text and video tasks through credits and events. pnpm validate:ai-channel checks pricing and routing.

Troubleshooting

A task fails with "AI scene is not available" or "AI provider is not available for this scene"

The scene has no active route, or the routed provider has no active provider scene for the requested output type. Route the scene on Scene routing and check that both the provider and the provider scene are active. No credits are taken.

A task fails with "S06 insufficient credits"

The user's available balance is lower than the price. Grant credits from Overview → Users or lower the price. No provider call is made.

Users pay an old price

The credit price changed after the provider scene was saved. Open the provider scene and click Save again.

Reference

Next steps