ai-gateway

Overview

AI Gateway module for calling Base44’s managed AI models from your own code. Call connection() to get a baseURL, token, and headers that authenticate as your Base44 app. An OpenAI-compatible client is any library, such as the openai SDK or the Vercel AI SDK, that has the same request and response format as OpenAI’s API and lets you point it at a custom baseURL instead of OpenAI’s own servers. Pass connection()’s values to one of these clients and it works against Base44’s gateway exactly as it would against the provider directly, no separate account, API key, or billing setup with the underlying model provider required. The optional provider picks the API you connect to:

openai (default): OpenAI-compatible chat completions, image, and video endpoints.
typesafe: structured evaluations with the jev model.

Call connection() from a backend function rather than the browser. This keeps your instructions, tools, and business logic server-side, and lets you enforce your own auth, rate, and spend limits around the call. Which token it returns depends on the authentication mode, described below.

OpenAI-compatible models

You can use any of the models available through InvokeLLM. Pass 'automatic' to let Base44 choose one, or pin a specific model such as 'claude_sonnet_4_6', 'gpt_5_5', or 'gemini_3_1_pro'.

Images

The gateway also serves OpenAI’s image endpoints, /images/generations and /images/edits, so you can generate images and edit them using reference images. Image requests use their own set of models. Pass 'automatic' to let Base44 choose one, or pin a model such as 'gemini_3_1_flash_image' or 'gpt_image_2'. For request options, the full model list, and limits, see Generate images with the AI Gateway.

Video

The gateway also serves OpenAI’s video endpoints, /videos, so you can generate video from a prompt, from a still image, or from existing media. Video generation is asynchronous. POST /videos returns a job, and you poll GET /videos/{id} until its status is completed or failed, which can take minutes. Video models are their own set, and there’s no automatic option, so pin a model such as 'veo_3_1_fast' or 'seedance_2'. For request options, the full model list, and limits, see Generate video with the AI Gateway.

Structured evaluations

The typesafe provider runs the jev evaluation model through @ai-sdk/typesafe-ai and experimental_evaluate from the ai package, version 7.0.105 or later. Pass evaluationModel("jev"), and note that the gateway rejects other model IDs, such as "jev-latest". Give it some app state and a set of questions, each a choice, score, or boolean. Choice and score answers come back with probabilities per option, and boolean answers with a single probability of true. Use it to classify, score, or route records, then apply your own thresholds and actions in code.

Authentication Modes

The mode determines which token connection() returns:

Service role authentication (base44.asServiceRole.aiGateway): Returns the app’s service-role token. Use it server-side. Calls from the browser or with a user’s token get a 403 and the error code ai_gateway_requires_service_role. It also works when no user is signed in, such as from a scheduled automation.
User authentication (base44.aiGateway): Returns the signed-in app user’s token. The gateway accepts it only on apps shared privately or with your workspace.

The mode decides which token you get and whether the gateway accepts the call. It grants the model no extra reach, because the gateway runs a model and never touches your data. Access to your app’s data comes from the base44.entities calls you write around the gateway call, so pick the mode for those on their own merits rather than matching this one.

Billing and limits

Requests are billed to your app’s credit quota, which is the same shared quota your app’s built-in AI features use, and isn’t split per user. If the app runs out of credits, the gateway stops working for every user of the app until the quota resets. A request is rejected before the model runs if the app is out of credits. If you need to cap usage per user, build that check yourself, for example by tracking calls per user in your own entity.

Methods

connection()

connection(options?): AiGatewayConnection

Gets the connection details for the Base44 AI Gateway. Returns the baseURL, token, and headers to pass to the selected provider client.

Parameters

AiGatewayConnectionOptions

Provider selection. Omit it to use the OpenAI-compatible gateway.

Properties

"openai" | "typesafe"

Gateway provider to connect to. Defaults to openai.

Returns

AiGatewayConnection Connection details for the Base44 AI Gateway.

Properties

string

required

Base URL of the selected gateway provider.

string

required

Bearer token that authenticates the request. The mode you call connection() from determines whose token it is.

Record<string, string>

required

Extra headers to send with every gateway request. Pass them to your client’s header option, such as defaultHeaders for the openai SDK and TanStack AI, or headers for the Vercel AI SDK.On a client from createClientFromRequest(), this carries the signed Base44-State the platform attached to the request, which a workspace IP allowlist requires. Otherwise it’s empty.

Examples

import { createClientFromRequest } from "@base44/sdk";
import OpenAI from "openai";

// Runs inside a backend function
const base44 = createClientFromRequest(request);
const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
const openai = new OpenAI({ baseURL, apiKey: token, defaultHeaders: headers });

const response = await openai.chat.completions.create({
  model: "automatic",
  messages: [{ role: "user", content: "Summarize this week's top support tickets." }],
});

console.log(response.choices[0].message.content);

import { createClientFromRequest } from "@base44/sdk";
import { ToolLoopAgent, tool, stepCountIs, hasToolCall } from "ai";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { z } from "zod";

// Runs inside a backend function, reviewing a return request
const base44 = createClientFromRequest(request);
const returnRequest = await base44.entities.ReturnRequest.get(returnId);
const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
// Point any OpenAI-compatible client at `baseURL` with `apiKey: token` and `headers`.
const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });

const agent = new ToolLoopAgent({
  model: models("automatic"),
  instructions:
    "Decide whether this return looks fine or needs the owner's attention. " +
    "Check the customer's past orders, then submit your verdict.",
  tools: {
    searchOrders: tool({
      description: "This customer's past orders, optionally filtered by status",
      inputSchema: z.object({ status: z.string().optional() }),
      execute: ({ status }) => {
        const query = { customer_email: returnRequest.customer_email };
        if (status) query.status = status;
        return base44.entities.Order.filter(query, "-created_date", 50);
      },
    }),
    submitVerdict: tool({
      description: "Record the final verdict",
      inputSchema: z.object({ decision: z.enum(["approved", "flagged"]), reason: z.string() }),
      execute: ({ decision, reason }) =>
        base44.entities.ReturnRequest.update(returnId, { status: decision, review_note: reason }),
    }),
  },
  stopWhen: [stepCountIs(8), hasToolCall("submitVerdict")],
});

await agent.generate({ prompt: `Review this return request: ${JSON.stringify(returnRequest)}` });

import { createClientFromRequest } from "@base44/sdk";
import { generateImage } from "ai";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

// Runs inside a backend function
const base44 = createClientFromRequest(request);
const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });

const { image } = await generateImage({
  model: models.imageModel("automatic"),
  prompt: "A watercolor illustration of a lighthouse at dawn",
  // Base44 options go under the provider name you passed above
  providerOptions: { base44: { aspect_ratio: "16:9" } },
});

const file = new File([image.uint8Array], "lighthouse.png", { type: image.mediaType });
const { file_url } = await base44.integrations.Core.UploadFile({ file });

import { createClientFromRequest } from "@base44/sdk";

// Runs inside a backend function
const base44 = createClientFromRequest(request);
const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();

const response = await fetch(`${baseURL}/videos`, {
  method: "POST",
  headers: { ...headers, Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "veo_3_1_fast",
    prompt: "A lighthouse beam sweeping across a calm sea at dawn",
    seconds: 8,
  }),
});

// Video generation takes minutes, so store the id and poll it from a later request
const { id } = await response.json();
await base44.asServiceRole.entities.Clip.update(clipId, { video_id: id });

import { createClientFromRequest } from "@base44/sdk";
import { experimental_evaluate as evaluate } from "ai";
import { createTypeSafeAi } from "@ai-sdk/typesafe-ai";

// Runs inside a backend function
const base44 = createClientFromRequest(request);
const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection({ provider: "typesafe" });
const typesafe = createTypeSafeAi({ baseURL, apiKey: token, headers });

const { answers, providerMetadata } = await evaluate({
  model: typesafe.evaluationModel("jev"),
  maxRetries: 0, // Avoid automatic replays of billed requests
  state: { message: "Please refund today's duplicate charge." },
  questions: {
    department: {
      type: "choice",
      instructions: "Which team should handle this?",
      criteria: { billing: "Payments and refunds", support: "Other requests" },
    },
    urgency: {
      type: "score",
      instructions: "How urgent is this?",
      criteria: ["No deadline", "Requested today", "Immediate emergency"],
    },
    refund: { type: "boolean", instructions: "Is a refund explicitly requested?" },
  },
});

// answers.department → { type: "choice", choice: "billing", probabilities: { billing: 0.97, support: 0.03 } }
// answers.urgency    → { type: "score", score: 1.2, probabilities: { 0: 0.1, 1: 0.6, 2: 0.3 } }
// answers.refund     → { type: "boolean", probability: 0.99 }
// Choice and score confidence is in providerMetadata.typesafe.confidence
// Pick your own thresholds and act on them in code
const autoRefund = answers.department.choice === "billing" && answers.refund.probability > 0.9;

Get Started

SDK Reference

Overview

OpenAI-compatible models

Images

Video

Structured evaluations

Authentication Modes

Billing and limits

Methods

connection()

Parameters

Returns

Examples

​Overview

​OpenAI-compatible models

​Images

​Video

​Structured evaluations

​Authentication Modes

​Billing and limits

​Methods

​connection()

​Parameters

​Returns

​Examples

Overview

OpenAI-compatible models

Images

Video

Structured evaluations

Authentication Modes

Billing and limits

Methods

connection()

Parameters

Returns

Examples