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
- At least one provider with a provider scene. See Connect an AI provider.
- An admin account with
ai.readandai.write. - A test user with credits. See Charge usage with credits.
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
sizeorduration. 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.04is 4 cost credits. With a 50% markup the user pays 6 credits. - A rate of
1000000total 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/ailists 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/failedwith the provider's error. /setupreports 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.