@inferall/sdk

Official TypeScript SDK for the InferAll AI gateway. One API, every model provider — OpenAI, Anthropic, Google Gemini, Replicate, and more — behind a single bearer token.

This is the TypeScript counterpart to the inferall-ai Python package and mirrors its surface one-to-one.

Zero runtime dependencies. The client uses only the platform fetch API, so it ships cleanly into Node, edge functions, and browsers. ESM, CJS, and full type declarations are all bundled.

Install

npm install @inferall/sdk

Requires Node 18+ (or any runtime with a global fetch).

Quick start

import { Inferall } from "@inferall/sdk";

const ai = new Inferall(); // reads INFERALL_API_KEY from the environment

// The built-in default is Gemini, which is a PAID model. On the no-card trial
// pass a free NVIDIA model so this first call succeeds.
console.log(
  await ai.text("Summarize the theory of relativity in two sentences.", {
    provider: "nvidia",
    model: "nvidia/nemotron-3-ultra-550b-a55b",
  }),
);

Explicit credentials

const ai = new Inferall({ apiKey: "ifu_..." });

System prompt + custom model

await ai.text("Translate to French: 'Where is the library?'", {
  system: "You are a careful translator.",
  provider: "openai",
  model: "gpt-4o-mini",
  temperature: 0.2,
});

Multi-turn chat

await ai.chat([
  { role: "user", content: "Hello!" },
  { role: "assistant", content: "Hi there — how can I help?" },
  { role: "user", content: "What's 2 + 2?" },
]);

Vision

import { readFile } from "node:fs/promises";

const imageBase64 = (await readFile("receipt.jpg")).toString("base64");

await ai.vision(imageBase64, "What's the total on this receipt?");

Raw responses

When you need access to tool calls, automatic-fallback metadata (fallback_used / actual_provider), or any provider-specific field, use generate() to get the full payload:

const raw = await ai.generate({
  provider: "anthropic",
  model: "claude-sonnet-4-6",
  operation: "chat",
  messages: [{ role: "user", content: "..." }],
});

Environment variables

| Variable | Purpose | | ------------------- | ------------------------------------------------------------------- | | INFERALL_API_KEY | Bearer token. Used when apiKey isn't passed to the constructor. | | INFERALL_BASE_URL | Override the gateway URL (default https://api.inferall.ai). | | AI_GATEWAY_KEY | Legacy fallback for INFERALL_API_KEY (recognised for back-compat).| | AI_GATEWAY_URL | Legacy fallback for INFERALL_BASE_URL. |

Environment variables are only read in runtimes that expose process.env (Node, most edge functions). In the browser, pass apiKey / baseURL explicitly.

Errors

Gateway failures throw InferallError. A status of 0 indicates a transport-level failure (network error or timeout) rather than an HTTP error response.

import { Inferall, InferallError } from "@inferall/sdk";

const ai = new Inferall();
try {
  await ai.text("...");
} catch (err) {
  if (err instanceof InferallError) {
    console.error(err.status, err.body);
  }
}

Python ↔ TypeScript

| Python (inferall-ai) | TypeScript (@inferall/sdk) | | ---------------------------------- | ------------------------------------------- | | from inferall import Inferall | import { Inferall } from "@inferall/sdk" | | Inferall(api_key=...) | new Inferall({ apiKey: ... }) | | ai.text(prompt, system=...) | ai.text(prompt, { system: ... }) | | ai.chat(messages) | ai.chat(messages) | | ai.vision(img_b64, prompt) | ai.vision(imgBase64, prompt) | | ai.generate(provider=..., ...) | ai.generate({ provider: ..., ... }) | | InferallError | InferallError |

Keyword arguments map to a trailing options object; snake_case parameters become camelCase (max_tokens → maxTokens, base_url → baseURL). Behaviour (defaults, env-var resolution, the /ai/v1/generate route, and response normalization) is identical.

License

MIT