> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started
> Call the AI Gateway from a Bijection action with the OpenAI SDK, the Agent component, the Vercel AI SDK, or fetch
Call models from an [action](/functions/actions). The gateway authenticates
with a short-lived token from `getServiceToken("ai-gateway")`. Model names use the `provider/model` form in
[Models](/ai-gateway/models).
## OpenAI SDK
The gateway is OpenAI-compatible. Set `baseURL` to the gateway and pass
`getServiceToken` as the API key:
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install openai
```
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { action } from "./_generated/server";
import { v } from "bijection/values";
import OpenAI from "openai";
import { getServiceToken } from "bijection/server";
export const chat = action({
args: { prompt: v.string() },
handler: async (ctx, { prompt }) => {
const openai = new OpenAI({
baseURL: "https://ai-gateway.bijection.com/v1",
apiKey: () => getServiceToken("ai-gateway"),
});
const completion = await openai.chat.completions.create({
model: "openai/gpt-4o-mini",
messages: [{ role: "user", content: prompt }],
});
return completion.choices[0].message.content;
},
});
```
## Agent component
Pass `bijectionGateway` as `languageModel` on
[`@bijection-dev/agent`](/agents/getting-started). It obtains the token for you:
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install @bijection-dev/agent @bijection/ai-sdk-provider
```
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { Agent } from "@bijection-dev/agent";
import { bijectionGateway } from "@bijection/ai-sdk-provider";
import { components } from "./_generated/api";
const agent = new Agent(components.agent, {
name: "Support agent",
languageModel: bijectionGateway("openai/gpt-4o-mini"),
instructions: "You answer questions about our product.",
});
```
[Workflows](/agents/workflows) that call `agent.generateText` use that same
model. For the [RAG component](/agents/rag), use
`bijectionGateway.embeddingModel(...)` as its embedding model.
## Vercel AI SDK
`bijectionGateway` works with `generateText`, `streamText`, `embed`, and
`embedMany` from the [Vercel AI SDK](https://ai-sdk.dev/). Use
`@bijection/ai-sdk-provider` with AI SDK 7.0.105 or later. The provider works in the default runtime and
[Node.js actions](/functions/runtimes).
For a Node.js action, set
[`node.nodeVersion`](/config/bijection-json#configuring-the-node-js-version) to
`"22"` or `"24"` in `bijection.json`. The default Bijection runtime doesn't need this
setting.
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install @bijection/ai-sdk-provider ai
```
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { action } from "./_generated/server";
import { v } from "bijection/values";
import { generateText } from "ai";
import { bijectionGateway } from "@bijection/ai-sdk-provider";
export const chat = action({
args: { prompt: v.string() },
handler: async (ctx, { prompt }) => {
const { text } = await generateText({
model: bijectionGateway("openai/gpt-4o-mini"),
prompt,
});
return text;
},
});
```
Stream with `streamText`:
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { streamText } from "ai";
import { bijectionGateway } from "@bijection/ai-sdk-provider";
const result = streamText({
model: bijectionGateway("openai/gpt-4o-mini"),
prompt,
});
for await (const chunk of result.textStream) {
console.log(chunk);
}
```
### Choose a model interface
For text generation, start with `bijectionGateway(model)`, which uses Chat
Completions across model providers. Use the native Messages or Responses
interface when you need endpoint-specific provider features:
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const messagesModel = bijectionGateway.messages("anthropic/claude-sonnet-4.5");
const responsesModel = bijectionGateway.responses("openai/gpt-5");
```
The Responses endpoint is stateless. The provider sets `store: false`; it does
not support `store: true` or `previous_response_id`.
### Decisions with Jev
**Decisions is in alpha**
`bijectionGateway.evaluationModel()` uses `/alpha/decisions`. The endpoint and AI
SDK's experimental evaluation interface may change during alpha.
Use AI SDK's `evaluate` to classify or score data with Jev from an action:
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { experimental_evaluate as evaluate } from "ai";
import { bijectionGateway } from "@bijection/ai-sdk-provider";
const decision = await evaluate({
model: bijectionGateway.evaluationModel("typesafe/jev-1.13"),
state: { ticket: "Customer cannot sign in" },
questions: {
priority: {
type: "choice",
instructions: "Choose the response priority",
criteria: {
urgent: "Respond now",
normal: "Respond today",
},
},
},
});
console.log(decision.answers.priority.choice);
```
Questions can use `choice`, `score`, or `boolean`. Boolean answers contain a
`probability` between 0 and 1. The provider translates this to the HTTP API's
`noul` question type and authenticates with `getServiceToken("ai-gateway")`.
Pass `abortSignal` to `evaluate` to cancel a request.
### Embeddings
Create embeddings with `embedMany`. The AI SDK automatically splits batches
larger than the gateway's 512-input limit:
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { embedMany } from "ai";
import { bijectionGateway } from "@bijection/ai-sdk-provider";
const { embeddings } = await embedMany({
model: bijectionGateway.embeddingModel("openai/text-embedding-3-small"),
values: ["hello", "world"],
});
```
### Images and videos
Use `bijectionGateway.imageModel()` with `generateImage`, or
`bijectionGateway.videoModel()` with `experimental_generateVideo` and
`experimental_startVideo`. Image and video generation are in alpha. See
[Images and videos](/ai-gateway/images-and-videos) for examples and callback
handling.
## Manual fetch
Use `fetch` when you want the HTTP API without an SDK. Mint a token, then send
it as `Authorization: Bearer `:
```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { action } from "./_generated/server";
import { v } from "bijection/values";
import { getServiceToken } from "bijection/server";
export const chat = action({
args: { prompt: v.string() },
handler: async (ctx, { prompt }) => {
const token = await getServiceToken("ai-gateway");
const response = await fetch(
"https://ai-gateway.bijection.com/v1/chat/completions",
{
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "openai/gpt-4o-mini",
messages: [{ role: "user", content: prompt }],
}),
},
);
return await response.json();
},
});
```
For Decisions requests with `fetch`, see the
[HTTP API example](/ai-gateway/api#post-/alpha/decisions).
See [HTTP API](/ai-gateway/api) for request and response shapes.
## Local development
Local development requires an up-to-date `bijection` package and local backend,
and a deployment linked to a project whose team has AI Gateway access. From your
project directory, run:
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection login
bijection deployment select local
bijection dev
```
Restart `bijection dev` after signing in if it was already running, and accept
the backend upgrade if prompted. The examples above, including
`getServiceToken("ai-gateway")`, work unchanged. See
[Local deployments](/cli/local-deployments-for-dev) for more setup options.
Inference runs in the cloud and is charged to the linked project's team.
Anonymous local deployments cannot use the gateway.
## Token and timeouts
Call `getServiceToken("ai-gateway")` inside an action whenever a gateway request
needs a credential. It returns a short-lived token scoped to your deployment;
the action runtime caches and refreshes it as needed. Keep the token private.
Don't return it to clients, store it in environment variables, or cache it
yourself.
The request runs inside your action, so a long completion can hit the
[action timeout](/production/state/limits#execution-time-and-scheduling) (30
minutes in the Bijection runtime, 10 minutes in Node) and fail as an action error
rather than a gateway error.
If getting a token fails with `AiGatewayDisabled` or `AiGatewayUnavailable`, see
[Who can use it](/ai-gateway/overview#who-can-use-it).