Kernlift

Connect an AI provider

An upstream AI account and its models are saved in the admin console and ready to be routed to your scenes.

A provider is one upstream API account, such as OpenAI, Gemini, Cloudflare Workers AI or any HTTP API that returns JSON. A provider scene is one concrete model or endpoint under it. Both are configured on Settings → AI Config, with no code change and no environment variables.

Before you begin

  • An account with the provider, an API key, the API base URL and the model IDs from its documentation.
  • An admin account with ai.read and ai.write.

Pick how you connect the provider by what it serves:

ProviderOutput typeWhat you configure
OpenAI, or any OpenAI-compatible chat APItextOpenAI protocol, a base URL, an API key and a model ID
Google GeminitextGemini protocol, a base URL, an API key and a model ID
Cloudflare Workers AItextEdge inference and a model ID; works only on Workers with the ai binding
An HTTP API that returns JSON (image, video, audio)image, video, audioThe endpoint, request parameters, how results come back, and response parsing

Prepare credentials with the model provider

ProviderChoose it for
OpenAIOpenAI-compatible text generation
Google GeminiText generation through the Gemini protocol
Cloudflare Workers AIRun a text model through a Worker binding

For a custom HTTP image, audio or video API, capture a real provider response before setting the parse paths. The steps below cover endpoint and result handling.

Add the provider

Open the form

Go to Settings → AI Config (/admin/config/ai), open Providers and click Add provider.

Identify the provider

Enter a Display name and a Code such as openai. The code is saved in lowercase with hyphens and appears in the webhook callback URL. Set Status to Active.

Set the base request

  • Method and Base URL: usually POST, and the API base URL. For the OpenAI protocol the chat completions path is appended to it.
  • API key secret: the key from the provider dashboard. It is stored as a secret and an Authorization row referencing it is added to Request headers. Leave it blank later to keep the stored key.
  • Request headers and Request parameters: optional headers and body fields sent on every call. Values can use {{prompt}}, {{input}} and {{metadata.<name>}}. Never paste a key into a header value.

Choose result handling and parsing

Text is always Direct response. For image, video and audio providers that finish later, choose Status polling or Webhook push. See Receive async results.

For those providers, fill in Upstream task ID path, Status path, Output path, Error path and Event ID path (defaults $.id, $.status, $.output, $.error), and in Status mapping list which provider status strings mean Queued, Running, Succeeded, Failed and Canceled, comma-separated. Paste a real response and click Test parser.

Save

Leave Use system default pricing ticked, or untick it to set Base cost credits and Markup for this provider. Click Save. The provider appears in the list.

Add a model

Describe the model

In the provider's row, click Provider scenes, then Add provider scene. Under Provider scene, fill in Provider scene code, Provider scene name, Output type and Status.

Set the request

Under Provider scene request:

  • Text: choose Protocol (OpenAI protocol, Gemini protocol or Edge inference) and enter the Model ID exactly as the provider names it, for example gpt-4o-mini or gemini-2.5-flash. The request goes to the provider's Base URL.
  • Image, video, audio: enter the full Provider scene endpoint, or leave it empty to use the provider's Base URL. Add headers or parameters only this model needs. Empty sections inherit the provider. Click Preview under Request preview to see the rendered request.

Under Provider scene result delivery, leave Inherit unless this model returns results differently from the rest of the provider.

Price it and save

Choose a Pricing mode under Provider scene pricing, as described in Price a provider scene, and click Save.

Keys in the environment are ignored

Only the key saved on the provider is used. Environment variables such as OPENAI_API_KEY are not read.

Verify

In the provider scenes list, Routing readiness shows Ready, or what is missing: Missing endpoint, Missing pricing, Missing protocol or model ID, Missing polling URL or Missing webhook secret. A ready provider scene can now be picked on Scene routing. pnpm validate:ai-channel checks the channel schema, parsing and pricing.

Troubleshooting

Chat fails with "AI channel ... is not configured"

The provider has no API key in its request headers. Save API key secret on the provider, or add an x-goog-api-key header for a Gemini provider. Chat reads the bearer token for OpenAI, and x-goog-api-key, x-api-key or a bearer token for Gemini.

Chat fails with "Provider scene chat protocol is not configured"

The provider scene routed from the chat scene has no protocol or model ID. Set both on the provider scene.

Edge inference is unavailable

The Workers AI binding only exists on Cloudflare Workers with the ai binding in wrangler.jsonc. Use the OpenAI or Gemini protocol in other runtimes. See Deploy to Cloudflare Workers.

The provider scene is not offered on Scene routing

Only active, ready provider scenes with the same output type as the scene are listed. Check Routing readiness, Status and Output type.

Reference

Next steps