Add AI to your app
Call chat models on your buyer's own OpenRouter key with the ambient window.panoplyAI API, and let them pick a model with Panoply's model picker
An app can call AI models without bundling their cost into its price. Each buyer's calls run on their own OpenRouter key, held in Panoply's Key Vault, so the buyer pays OpenRouter directly for what they use. Your page never sees the key, and neither does your code anywhere else. See Connect your own AI keys for how the Vault works.
window.panoplyAI is defined in every hosted app, before your own scripts run. It talks to your app's own address, so a content security policy needs nothing beyond 'self'.
Connecting a key
The buyer's OpenRouter key is typed in a window Panoply opens, never in your page. Call keys.open straight from a click:
const key = await panoplyAI.keys.open('openrouter') // { provider, last4, updatedAt, status, limit, ... } once it is stored
Show last4, status and limit from keys.list() on your settings screen, "Replace" is keys.open again, and "Remove" is keys.delete('openrouter'). There is no keys.set: it rejects key_entry_moved, and an app with its own field asking for a key breaks Panoply's rules. The codes keys.open rejects with, and how the window works, are in Connect your own AI keys.
Who pays what
The buyer pays their provider. Panoply records what each call cost, as the provider reported it, never an estimate, so the buyer can see their spend with panoplyAI.costs(). When the provider reports no cost, the answer says so (cost: null, costReported: false); it is never zero. You, the creator, see only a daily total per app, with no buyer, model or call in it, and only for days with at least five paying buyers.
The prices the model list shows are for display. What a call costs is what the provider reports.
Chat
const stream = panoplyAI.chat({
model, // a vendor/model id: the one your buyer chose in the picker below
messages: [{ role: 'user', content: 'Suggest a name for a synth patch' }],
})
for await (const { text } of stream) output.textContent += text
const { cost, costReported } = await stream.result
model is required: a vendor/model id from the list below, the one your buyer chose. Panoply has no default model, so a call with no model rejects ai_model_required before anything is sent, and costs nothing; the old value "recommended" rejects ai_model_invalid. complete(opts) takes the same options and resolves to the whole answer. Add schema for structured output. A call that fails part way still carries cost and costReported, since it may have cost money.
Each delta is { text, endpoint, tokensIn, tokensOut }, and stream.result (and complete) resolves to { text, model, generationId, cost, costReported, recorded, endpoint, tokensIn, tokensOut }. endpoint is the provider OpenRouter routed the call to ("Anthropic", "Amazon Bedrock"): it is null until the provider's stream names it, which is normally before the first text, so you can show it while the answer is still being written. tokensIn and tokensOut are the provider's own counts. Providers normally send them with the last piece of the stream, so expect null on the deltas and read them from stream.result; they are null there too when the provider reported none, never zero. These are the same three fields a row of panoplyAI.costs() has.
for await (const { text, endpoint } of stream) {
if (endpoint) providerLabel.textContent = endpoint
output.textContent += text
}
const { tokensIn, tokensOut, cost } = await stream.result
Choosing a model
const { models, companies, total, startModel } = await panoplyAI.models.list({ tools: true, q: 'claude', limit: 20 })
tools and structuredOutputs keep only models that can. q searches names and ids, id asks for one model, and limit is 1 to 500 (default 100). total is how many models match, before limit. companies lists every company with a model in that list, each as { id, name, count } (Anthropic, Google, Meta and so on), whatever limit and company say; company (one of those ids) narrows models to that company's. startModel is the model you chose as your app's starting model in its listing settings, or null; panoplyAI.models.start() resolves to it. Each model has id, name, company: { id, name }, contextLength, tools, structuredOutputs, tags and a price, which is null when nobody knows it, { unit: "mtok", inputUsd, outputUsd } per million tokens, or { unit: "request", amountUsd }. The list can fail with models_unavailable.
The picker
Panoply ships a model picker so you do not have to build one. Load it once, then use the element:
<panoply-model-picker tools></panoply-model-picker>
await panoplyAI.ui.load()
picker.addEventListener('change', (e) => { model = e.detail.model }) // a vendor/model id
It is a field showing the chosen model. Click it and a menu opens in two steps. First the providers behind the models (Anthropic, Google, Meta and so on), each with how many models it has, under a "filter providers" box. Choose one and the menu shows "‹ Providers" and that provider's name, a filter box, then one row per model: its id, and under it its context size and its input and output price in dollars per million tokens. The chosen model is tinted and checked. Type to narrow the list by name or id; Escape or a click elsewhere closes it, and the arrow keys and Enter work from the keyboard. Provider rows are 44 px high and model rows 56 px. On a phone (600 px wide or less) the menu opens as a sheet from the bottom of the screen, over a dimmed page, with 44 px buttons; tapping the dimmed page closes it.
Panoply chooses no model for the buyer: until someone chooses, the field reads "Choose a model", unless you set a starting model in your listing's settings, in which case the picker starts on that model. The buyer can change it either way, and your app should remember what they chose.
Attributes: tools and structured-outputs (only models that can), value and theme (light or dark; without it the picker follows the system). Read and set element.value: it is the chosen model's id, or an empty string until someone chooses. element.startModel is your starting model's id, or null; while nothing else is chosen element.value reports it, with no change event, since nobody chose it. A change event fires when someone chooses a row, with detail: { model, info }: model is the model's id and info is its entry from the list. Send element.value as model to panoplyAI.chat: with none chosen it is an empty string, and the call rejects ai_model_required. The picker's script comes from your app's own address; if it cannot load, ui.load() rejects with ai_ui_unavailable.
Making it match your app
Every colour, font and spacing is a CSS custom property you can set on the element. None is required: without them the picker wears Panoply's own look, in light or dark.
panoply-model-picker {
--panoply-picker-bg: #0f172a;
--panoply-picker-fg: #e2e8f0;
--panoply-picker-muted: #94a3b8;
--panoply-picker-border: #1e293b;
--panoply-picker-hover: #1e293b;
--panoply-picker-accent: #38bdf8;
--panoply-picker-radius: 6px;
--panoply-picker-font: 'Inter', sans-serif;
--panoply-picker-mono-font: 'JetBrains Mono', monospace;
--panoply-picker-row-height: 40px;
--panoply-picker-menu-max-height: 420px;
}
| Property | What it sets | Default |
|---|---|---|
--panoply-picker-bg | the picker's background | Panoply's panel colour (white, or near-black with the theme) |
--panoply-picker-fg | text | Panoply's text colour |
--panoply-picker-muted | context sizes, prices, placeholders, hints | Panoply's secondary text colour |
--panoply-picker-border | the outline of the picker, field, filter and menu | Panoply's light border |
--panoply-picker-hover | the row or field under the pointer | Panoply's input colour |
--panoply-picker-accent | the chosen model's check, the focus ring, "‹ Providers" and the model-count number | Panoply purple |
--panoply-picker-radius | the picker's corner radius, and the menu's unless set below | 10px |
--panoply-picker-font | the font for everything except model ids | DM Sans, else the system font |
--panoply-picker-mono-font | the font for model ids | JetBrains Mono, else the system monospace |
--panoply-picker-field-bg | the field's background | Panoply's input colour |
--panoply-picker-menu-bg | the menu's background | --panoply-picker-bg |
--panoply-picker-input-bg | the filter box's background | Panoply's input colour |
--panoply-picker-selected-bg | the chosen row's tint | a light purple tint |
--panoply-picker-selected-fg | the chosen row's text | --panoply-picker-fg |
--panoply-picker-tag-bg | the model-count badge's background | a light purple tint |
--panoply-picker-tag-fg | the model-count badge's text | --panoply-picker-accent |
--panoply-picker-price-fg | prices | --panoply-picker-muted |
--panoply-picker-shadow | the colour of the menu's shadow | black at 12% (42% dark) |
--panoply-picker-scrim | the dimmed page behind the phone sheet | black at 40% (62% dark) |
--panoply-picker-font-size | model ids, rows and the field | 14px |
--panoply-picker-small-size | context sizes, prices, the count badge, hints | 12px |
--panoply-picker-label-size | the label above the field | 13px |
--panoply-picker-label-display | set none to hide the "Model" label | block |
--panoply-picker-padding | space inside the picker | 12px |
--panoply-picker-field-padding | space inside the field | 8px 12px |
--panoply-picker-row-padding | space inside a row | 6px 12px |
--panoply-picker-row-height | the least height of a provider row (model rows are 56px) | 44px |
--panoply-picker-row-radius | a row's corner radius | 0 |
--panoply-picker-gap | the space between a row's columns | 12px |
--panoply-picker-input-radius | the field's and the filter box's corner radius | 10px |
--panoply-picker-menu-radius | the menu's corner radius (the phone sheet's top corners are 16px) | --panoply-picker-radius |
--panoply-picker-menu-max-height | how tall the menu grows before it scrolls | 400px |
--panoply-picker-menu-min-width | the narrowest the menu is, when the field is narrower | 280px |
The key row, cost line and AI label
ui.load() adds three more elements beside the picker, so the parts every AI app needs look the same everywhere and match your app once you set their properties.
<panoply-key-row provider="openrouter" app-name="Travel Atlas"></panoply-key-row>
<article>
<panoply-ai-label></panoply-ai-label>
<p>…the model's answer…</p>
<panoply-cost-line cost="0.0042"></panoply-cost-line>
</article>
<panoply-key-row> connects the buyer's key. It reads panoplyAI.keys.list() when it is added to the page and shows one of five states, which it also puts on the element as data-state:
data-state | What the buyer sees | Buttons |
|---|---|---|
none | "Connect your OpenRouter key" and "Opens a Panoply window where you paste your key. Travel Atlas never sees it." | Connect |
waiting | a pulsing dot and "Finish in the Panoply window" | Cancel |
blocked | "Your browser blocked the Panoply window. Allow pop-ups for this site, then try again." | Try again |
rejected | "OpenRouter rejected that key." | Connect another key |
connected | "Key ending 7f3a · Work key · limit $10.00 · $8.42 left" (the name, limit and amount left only when there are any) | Replace, Remove |
Connect, Try again, Connect another key and Replace call panoplyAI.keys.open straight from the click, as a browser requires for a popup; Cancel aborts the wait and Remove calls keys.delete. rejected means OpenRouter no longer accepts the stored key. The element fires change (bubbles, composed) on every state, with detail: { state, key }: key is the provider's row of keys.list() (last four, name, limit, amount left), never the key itself. element.state, element.key and element.refresh() are there for an app that wants them. Attributes: provider (openrouter, the default, or runware), app-name (your app's name in the sentence; "This app" without it) and theme. provider can be set as a property too (element.provider = 'runware'), which is how React 19 passes it. On a phone the buttons take the full width.
The "left" figure is OpenRouter's, read from the key's own record (limitRemaining in keys.list()). OpenRouter can take a while to bill a call, so right after an answer the figure may not have moved yet: call element.refresh() after a call if you want it re-read, and do not treat it as a live balance. What a call cost is the cost its answer carries.
<panoply-cost-line cost="0.0042"> goes under each answer: "This answer cost $0.0042", or "Cost unknown" when the provider reported none. Set cost from the cost that panoplyAI.chat returns, and cost-reported="false" when it returns costReported: false; an empty or missing cost also reads "Cost unknown". element.cost reads and sets it.
<panoply-ai-label> is a small outlined "Written by AI" for the top of each AI answer.
All three follow the system's light or dark setting unless you set theme, and every colour, font and size is a property you can set:
panoply-key-row { --panoply-key-accent-fill: #0ea5e9; --panoply-key-radius: 6px; }
panoply-cost-line { --panoply-cost-fg: #64748b; }
panoply-ai-label { --panoply-ai-label-fg: #0ea5e9; --panoply-ai-label-border: #0ea5e9; }
| Property | What it sets | Default |
|---|---|---|
--panoply-key-bg | the key row's background | Panoply's panel colour |
--panoply-key-fg | its text | Panoply's text colour |
--panoply-key-muted | the second line | Panoply's secondary text colour |
--panoply-key-border | its outline and the small buttons' outline | Panoply's light border |
--panoply-key-accent | the waiting dot and the focus ring | Panoply purple |
--panoply-key-accent-fill | the main button's fill | Panoply's purple fill |
--panoply-key-accent-fg | the main button's text | white |
--panoply-key-error | the blocked and rejected sentences | Panoply's error red |
--panoply-key-success | the connected line | Panoply's success green |
--panoply-key-radius | the row's corner radius | 10px |
--panoply-key-button-radius | the buttons' corner radius | 10px |
--panoply-key-button-height | the main button's height (48px on a phone) | 40px |
--panoply-key-padding | space inside the row | 12px 16px |
--panoply-key-font | its font | DM Sans, else the system font |
--panoply-key-mono-font | the font of the key's last four | JetBrains Mono, else the system monospace |
--panoply-key-font-size | its text size | 14px |
--panoply-key-small-size | the second line's size | 13px |
--panoply-cost-fg | the cost line's colour | Panoply's secondary text colour |
--panoply-cost-font | its font | DM Sans, else the system font |
--panoply-cost-font-size | its size | 12px |
--panoply-ai-label-fg | the label's text | Panoply purple |
--panoply-ai-label-border | its outline | Panoply purple |
--panoply-ai-label-bg | its fill | none |
--panoply-ai-label-font | its font | DM Sans, else the system font |
--panoply-ai-label-font-size | its size | 12px |
--panoply-ai-label-padding | space inside it | 2px 8px |
--panoply-ai-label-radius | its corner radius | fully rounded |
Developing locally
window.panoplyAI only exists in a hosted app. To build against it on your own machine, copy Panoply's development client into your app. It installs window.panoplyFiles beside it (see Files while developing). It has the same calls as the injected one (chat, complete, models.list, models.start, keys.list, keys.open, keys.delete, costs and ui.load, and the same error codes), so the code you write in development is the code you upload.
Copy it with the script that comes with Panoply, from your app's folder (<panoply> is your Panoply checkout):
node <panoply>/apps/marketplace/scripts/copyPanoplyAiDev.mjs src/panoply
It writes src/panoply/panoply-ai-dev.js and a small panoply-ai-dev.source.json naming the commit it came from. Run it with --check in your app's tests to learn when Panoply has changed the client. Then, in a Vite app, load it from src/main.js before anything calls panoplyAI:
// VITE_PANOPLY_AI is the one setting: "dev" on your machine, "production" (or unset) everywhere else.
// .env.development: VITE_PANOPLY_AI=dev .env.production: VITE_PANOPLY_AI=production
const mode = import.meta.env.VITE_PANOPLY_AI
if (import.meta.env.DEV && mode === 'dev') {
const { installPanoplyAIDev } = await import('./panoply/panoply-ai-dev.js')
installPanoplyAIDev({ mode })
}
// From here the app calls window.panoplyAI as it always does.
Run vite dev and call panoplyAI.keys.open('openrouter') from a click: the development client shows a plain dialog for your own OpenRouter key, checks it with OpenRouter and keeps it in this page's localStorage. There is no Key Vault.
The dialog has a second field, an optional name for the key, as Panoply's own window does. Your app sees a key's last four characters and the name that was typed, or null if none was, and nothing else of the key. A name is held to Panoply's rule (up to 50 characters of ordinary, visible text, with no line breaks or invisible characters), and the dialog refuses one that breaks it, as the window on Panoply does with key_name_invalid. Replacing a key shows the stored name in the field, and whatever it says when you save is what is kept, so clearing it removes the name. The name is never taken from OpenRouter's own label for the key: for a key you did not name there, that label is an abbreviation of the key itself, and showing it would put part of the key in your app.
The rest of what the client does: chat and complete call OpenRouter directly with that key, models.list reads OpenRouter's public model list and groups it into companies as the picker on Panoply does, ui.load() adds the same two-step <panoply-model-picker> and the same key row, cost line and AI label, and costs() lists the calls made since the page loaded, each with the cost OpenRouter reported (null when it reported none). Set installPanoplyAIDev({ mode, startModel: 'vendor/model' }) to give the picker the starting model your listing would carry.
To switch to production, set VITE_PANOPLY_AI=production: the development client does nothing and the page has no panoplyAI or panoplyFiles until your app is on Panoply, where the injected ones are there before your scripts run. No code changes. Three guards hold whatever the setting says. The development client runs only on localhost, 127.0.0.1 and *.localhost; it never installs when window.panoplyAI is already there, so on Panoply the injected client always wins (and an existing window.panoplyFiles is left alone); and only the exact setting dev turns it on.
What differs, because there is no Panoply behind it: a key is one OpenRouter key per browser address (a Runware key is not offered, and keys.open('runware') rejects key_provider_invalid); costs are not kept past a page reload; and the picker lists OpenRouter's catalogue without the per-model settings Panoply keeps for its own list.
Keep it out of your production build. The file asks for a key and calls OpenRouter with it, which Panoply's upload scan looks for in an app, so it must not be in what you upload. The dynamic import() above sits behind import.meta.env.DEV, which Vite replaces with false in vite build, so the build leaves the import out and the file never reaches dist. After a build, check: grep -rIl "openrouter.ai" dist should print nothing. A static import of the file, or a copy under public/, would ship it.
Model calls from your own Worker
If your app's model calls run in its own Worker rather than in the page, the Worker asks the Key Vault for the buyer's key with a vault token, and a key in the page's localStorage is no use to it. For that, run the local Key Vault stand-in on the same machine, from your Panoply checkout:
pnpm dev:vault # http://127.0.0.1:4950; PANOPLY_DEV_VAULT_PORT picks another port
While it runs, the development client keeps the key there instead of in localStorage (its dialog says so): keys.open stores the key in the stand-in, keys.list and keys.delete read and clear it from there, and the page's own chat calls go through it. A key entered once is then the key your Worker gets. Stop it and the client falls back to localStorage, and the key it held is gone with the process.
Point the Worker at it in local development only. A Worker that uses the Key Vault is configured with two addresses: the marketplace, where it asks for a vault token (POST /api/keyvault/app-token, and GET /api/ai/status), and the vault (GET /keys, POST /keys, DELETE /keys/openrouter, and /run/openrouter/api/v1/ for chat/completions, key and generation). In production they are https://panop.ly and https://keyvault.panop.ly; under wrangler dev set both to http://127.0.0.1:4950, in your local environment file (such as .dev.vars) and nowhere that is deployed. The Worker's code and calls do not change.
The stand-in is for one developer on one machine: it holds a single OpenRouter key in memory (and never on disk, even though it keeps files on disk, below), calls OpenRouter directly, accepts any PanoplyApp assertion without checking it (it knows no purchases, so every buyer id gets the one key), keeps no cost records, and answers only requests whose Host and Origin are local. It never prints or returns the key (a list shows its last four characters and the name that was typed, if any), and it refuses to start where a deploy platform's variables are set. It is not part of any deploy.
Files while developing
window.panoplyFiles (see Store files from your app) is installed by the same call as window.panoplyAI, and pnpm dev:vault is also the stand-in for Panoply's file storage. With it running, list, usage, upload, url, get and delete work on your machine with the results, the refusal codes and the limits they have on Panoply: a file over 95 MB is sent in 50 MB parts, a name is 1 to 255 characters, an upload over the quota rejects files_quota_exceeded with usedBytes, quotaBytes and requestedBytes in details, and the 10,001st file rejects file_limit_reached with fileCount and maxFiles. With the stand-in stopped, every call rejects files_not_enabled and url() returns null, as in a Panoply app that has no file storage.
Where things are kept, and what you can set:
- The files are kept in
apps/marketplace/.dev-vault-files/in your Panoply checkout (it is gitignored): each file's bytes inblobs/, and the records in one small table,files.json, beside them. They survive a restart ofpnpm dev:vault. To start empty, stop it and delete the folder. A key is never written there. - The quota is one setting,
PANOPLY_DEV_FILES_QUOTA_BYTES, a whole number of bytes (1 GiB when unset).usage().warnBytesis 80% of it. To seefiles_quota_exceededin your app, start the stand-in with a small one:PANOPLY_DEV_FILES_QUOTA_BYTES=1000000 pnpm dev:vault. Panoply sets each app's real figure at review, so a quota you test with here is yours to choose, not a promise of what your app will get. - Whose files: the page's calls are made as one app,
dev-client, so they share one quota. Files are kept per app name, and a caller using another name neither sees nor changes them.
What differs, because there is no Panoply behind it: url(id) returns an address on the stand-in (http://127.0.0.1:4950/__panoply/files/<id>?app=dev-client), not an address on your app, and it works as the src of an <audio>, <video> or <img> because that address names the app itself (those elements send no headers); there is no buyer session, so nothing expires or renews; and a file is not removed when a purchase is refunded or an account is deleted. The stand-in answers only local callers, like the rest of it.
Errors
Calls reject with { code, status, message }. The ones to handle:
| code | meaning |
|---|---|
ai_model_required | the call named no model: let the buyer choose one in the picker and send it as model (nothing was sent or charged) |
ai_model_invalid | model is not a vendor/model id (the old value "recommended" is refused too) |
ai_key_missing | the buyer has set no OpenRouter key for this app |
ai_key_rejected, ai_insufficient_credits | OpenRouter refused the key, or the buyer is out of credit |
ai_paused | Panoply has paused AI for everyone; nothing was charged |
models_unavailable | the model list could not be read; retry |
ai_ui_unavailable | the picker's script could not be loaded |
From your tools, and agents
An app that offers tools can call chat from tool code with ctx.panoply.ai.chat (declare the ai capability). It runs on the same key and writes the same cost row. Calls an agent makes through your tools are held to the agent's daily dollar cap, set by its custodian; see AI from a tool, and an agent's daily cap. The cap covers agents only: the page-side panoplyAI calls above, and any call made for a human (the buyer using the app or a tool themselves, or an install token with no agent), are not counted against any cap. An agent's own sign-in session is left out of the cap for now.