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.readandai.write.
Pick how you connect the provider by what it serves:
| Provider | Output type | What you configure |
|---|---|---|
| OpenAI, or any OpenAI-compatible chat API | text | OpenAI protocol, a base URL, an API key and a model ID |
| Google Gemini | text | Gemini protocol, a base URL, an API key and a model ID |
| Cloudflare Workers AI | text | Edge inference and a model ID; works only on Workers with the ai binding |
| An HTTP API that returns JSON (image, video, audio) | image, video, audio | The endpoint, request parameters, how results come back, and response parsing |
Prepare credentials with the model provider
| Provider | Choose it for |
|---|---|
| OpenAI | OpenAI-compatible text generation |
| Google Gemini | Text generation through the Gemini protocol |
| Cloudflare Workers AI | Run 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-miniorgemini-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.