Quickstart

This guide walks you through adding AI capabilities to your web app using BYOK API.

Prerequisites

A running BYOK bridge instance (default: http://localhost:8881)
Node.js 22+
An API key added to the bridge (OpenAI, Anthropic, or OpenRouter)

1. Install the client

npm install @byokapi/client ai

The ai package is Vercel's AI SDK v6, which BYOK API's transport models implement.

2. Create a client instance

import { ByokClient } from "@byokapi/client"

const client = new ByokClient({
  bridgeUrl: "http://localhost:8881/bridge",
  appName: "My App",
})

The bridgeUrl points to the bridge's iframe endpoint. The appName is shown to users in the consent popup.

3. Connect and request access

// Connect creates a hidden iframe and establishes the RPC channel
await client.connect()

// Request a grant for language model access
const result = await client.requestGrant({
  capabilities: ["language"],
})

if (result.type === "denied") {
  console.log("User denied access")
  return
}

When requestGrant is called, the bridge opens a consent popup asking the user to approve or deny access. If the user has previously granted access, the grant is restored automatically.

4. Use AI models

import { generateText } from "ai"

const provider = client.getProvider()

const { text } = await generateText({
  model: provider("gpt-4o"),
  prompt: "Explain quantum computing in one sentence.",
})

console.log(text)

The provider function returns a standard AI SDK LanguageModelV3 that proxies calls through the bridge. You can use any model ID that the bridge's configured providers support.

5. Stream responses

import { streamText } from "ai"

const { textStream } = streamText({
  model: provider("gpt-4o"),
  prompt: "Write a haiku about TypeScript.",
})

for await (const chunk of textStream) {
  process.stdout.write(chunk)
}

Streaming works the same as with the AI SDK — the bridge forwards chunks in real-time via the RPC channel.

Next steps

Architecture — understand how the bridge works under the hood
Grants — learn about capabilities and permission management
Client reference — full API documentation

On this page