Models and API keys

Every AI feature in Miraiclip talks to one small contract, ChatModel, so it works with any provider. @miraiclip/assistant ships adapters for OpenAI, Anthropic and Google Gemini, plus a catalog that covers OpenRouter, Groq, Mistral, DeepSeek, xAI, Together, Ollama, LM Studio and any OpenAI-compatible server.

You choose how keys are handled:

• Your keys: keys sit on your server, and users pick from the models you offer.
• Bring your own key (BYOK): each user adds their own provider key. It goes with each request to your server, which uses it for that call only and never stores it.
• Both: your models by default, and users can switch to their own key.

npm install @miraiclip/assistant

Pick a providerCopy Anchor Link

createChatModel builds a model for any provider in the catalog:

import { createAssistant, createChatModel } from "@miraiclip/assistant";

const model = createChatModel({
  provider: "anthropic", // "openai", "gemini", "openrouter", "groq", "ollama", …
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: "claude-sonnet-5-5", // optional where the provider has a default
});

const assistant = createAssistant({ model });

The default models are suggestions from when the package was released. Model names change often, so each adapter can list what the account can use right now:

import { createChatModel } from "@miraiclip/assistant";

const model = createChatModel({ provider: "gemini", apiKey: process.env.GEMINI_API_KEY });
const models = await model.listModels?.(); // [{ id: "gemini-3.8-flash", label: "Gemini 3.8 Flash" }, …]

AI_PROVIDERS is the catalog itself (id, label, wire format, base URL, key page, default and suggested models) if you want to build your own picker. aiProvider(id) returns one entry.

The adaptersCopy Anchor Link

You can also use each adapter directly:

Provider-specific state that has to survive a conversation rides on each tool call's meta. The agent loop keeps it, so you don't have to.

Read keys from the environmentCopy Anchor Link

chatModelsFromEnv builds a model for every provider whose key is set:

import { chatModelsFromEnv, routedChatModel } from "@miraiclip/assistant";

const models = chatModelsFromEnv(process.env, {
  onSkip: (provider, reason) => console.warn(`${provider}: ${reason}`),
});
const model = routedChatModel(models); // one model serving all of them

The list follows the catalog order, so the first entry is a sensible default.

Several providers as one modelCopy Anchor Link

routedChatModel(models) serves several adapters behind one ChatModel. Its model ids are provider/model, and a request's model picks both:

import { chatModelsFromEnv, createAssistant, routedChatModel } from "@miraiclip/assistant";

const model = routedChatModel(chatModelsFromEnv(process.env), { default: "anthropic" });
const assistant = createAssistant({ model, modelId: "gemini/gemini-3.8-flash" });

model.models;    // [{ id: "anthropic/claude-sonnet-5-5", … }, { id: "gemini/gemini-3.8-flash", … }, …]
model.providers; // [{ id: "anthropic", label: "Anthropic" }, …]

A bare model id goes to the adapter that lists it, else to the default adapter. No model means the default adapter's default model. listModels() merges every adapter's live list.

Let users bring their own keyCopy Anchor Link

Turn on userKeys in createChatHandler. A request can then carry the user's provider and key in headers. The handler builds a model for that one request and forgets the key:

// Server
import { chatModelsFromEnv, createChatHandler, routedChatModel } from "@miraiclip/assistant";

declare function canUseOwnKeys(request: Request): Promise<boolean>; // your plan check

const models = chatModelsFromEnv(process.env);
const handle = createChatHandler(models.length ? routedChatModel(models) : null, {
  basePath: "/api/assistant",
  userKeys: { providers: ["openai", "anthropic", "gemini", "openrouter"] },
  // Your auth and plan checks still run first.
  authorize: async (request) => {
    const byok = request.headers.has("x-ai-key");
    if (byok && !(await canUseOwnKeys(request))) return new Response("Your plan doesn't include your own keys", { status: 403 });
    return undefined;
  },
});

// Browser
import { createAssistant, remoteChatModel, type UserCredentials } from "@miraiclip/assistant";

let mine: UserCredentials | null = null; // set from your settings UI

const model = await remoteChatModel("/api/assistant", { credentials: () => mine });
const assistant = createAssistant({ model });

mine = { provider: "anthropic", apiKey: "sk-ant-…" }; // applies from the next call
const theirModels = await model.listModels?.(); // listed with the user's key

Pass null as the model to run with no server key at all: every user brings their own.

userKeyHeaders(credentials) builds these headers if you call the endpoint yourself.

When userKeys is on, GET {basePath}/ tells the browser what's allowed:

{
  "id": "router",
  "label": "AI models",
  "models": [{ "id": "anthropic/claude-sonnet-5-5", "label": "Anthropic · claude-sonnet-5-5" }],
  "providers": [{ "id": "anthropic", "label": "Anthropic" }],
  "userKeys": {
    "providers": [{ "id": "openai", "label": "OpenAI", "needsKey": true, "keyUrl": "https://platform.openai.com/api-keys", "defaultModel": "gpt-5.4-mini" }],
    "allowBaseUrl": false,
    "required": false
  }
}

needsKey: true means the server has no model of its own (or requires user keys): calls need the user's key. remoteChatModel exposes this as model.info.

Where the user's key livesCopy Anchor Link

The key is stored wherever your app keeps user settings: the browser (as the React template does), or your own database, encrypted. Either way it reaches the provider only through your server, for one request at a time. The handler never logs or stores it.

No backend: keys in the browserCopy Anchor Link

An app with no server at all can call providers straight from the browser with the user's own key. OpenAI, Anthropic, Gemini and OpenRouter accept cross-origin calls. browser: true adds what Anthropic needs for that:

import { createAssistant, createChatModel } from "@miraiclip/assistant";

declare const userKey: string; // typed in by the user, never yours

const model = createChatModel({ provider: "anthropic", apiKey: userKey, browser: true });
const assistant = createAssistant({ model });

In the React templateCopy Anchor Link

The Editor UI kit uses all of this:

• Put any provider key in .env.local (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, …) and restart pnpm dev. {PROVIDER}_MODEL picks the model.
• The dropdown under the Assistant's input picks the model: the server's models grouped by provider (Load all models… adds each provider's live list), plus the providers you've added a key for.
• The gear beside it adds your own API key: pick a provider, paste a key, pick a model, then Save and test. When the server allows custom addresses, you can also point it at your own OpenAI-compatible server.
• Every AI feature (Assistant, Ask AI in the code editor, Create with AI, Translate, Voiceover rewrite) uses the same choice.
• Bring-your-own-key is on by default on the dev server. AI_USER_KEYS=0 turns it off, AI_USER_KEYS_REQUIRED=1 refuses the server's keys, and AI_USER_KEYS_BASE_URL=1 allows custom addresses.

The code is in vite-plugins/assistant.ts (server) and src/features/assistant/aiSettings.ts (settings and the live model).

Other AI featuresCopy Anchor Link

Speech-to-text (@miraiclip/transcript: OpenAI, Deepgram) and voice and audio generation (@miraiclip/audio-sources: ElevenLabs, OpenAI) have their own vendor-neutral contracts and adapters. See Screen recordings for developers and Audio.

Tool definitions for your own loop come in all three vendor shapes: toToolDefinitions(catalog, { style: "anthropic" | "openai" | "gemini" }). See Tools from the command catalog.