Call the gateway

This page helps you pick a client and points to the setup for each. Every path below uses one credential and one host. Mint a key at the console, store it as CONIFER_API_KEY, and point the client at https://api.conifer.build.

export CONIFER_API_KEY='sk-conifer-…'

Which client#

The Conifer SDK is open source#

The SDK lives at ConiferKit/use-conifer in TypeScript and Python. It covers three things the OpenAI client cannot do. It returns an exact integer cost receipt on every response. It supports a server-enforced maxCostNanoUsd ceiling. It also raises distinct error types for “out of credit” and “your own ceiling refused this”.

Or the official packages#

The gateway speaks the OpenAI and Anthropic wires, so the official clients work against it as they are. The request body does not change. Only the base URL and the key do.

npm install openai

import OpenAI from "openai";

export function conifer() {
  const apiKey = process.env.CONIFER_API_KEY;
  if (!apiKey) {
    throw new Error("CONIFER_API_KEY is missing. Set it before calling the gateway.");
  }
  return new OpenAI({
    baseURL: process.env.OPENAI_BASE_URL ?? "https://api.conifer.build/v1",
    apiKey,
  });
}

export async function POST(req: Request) {
  const res = await conifer().chat.completions.create({
    model: "claude-haiku-4-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "three names for a build cache" }],
  });

  return Response.json({ content: res.choices[0].message.content });
}

If the project already builds its client from environment variables, set these and leave the source alone. The two base URLs differ. The OpenAI one carries the /v1 suffix and the Anthropic one does not.

export OPENAI_BASE_URL=https://api.conifer.build/v1
export OPENAI_API_KEY=$CONIFER_API_KEY

export ANTHROPIC_BASE_URL=https://api.conifer.build
export ANTHROPIC_API_KEY=$CONIFER_API_KEY

Coming from another gateway#

From Vercel AI Gateway, OpenRouter or Helicone, the mechanical change is two lines. Model ids need no rewriting. A namespaced id like anthropic/claude-opus-5 is accepted and served as the catalog’s claude-opus-5. The gateway returns the settled cost in the x-conifer-cost-nanousd header. The Conifer SDK copies it into the body as usage.cost, the field OpenRouter used, so an existing cost column keeps working. The official OpenAI client does not do this on its own.

- baseURL: "https://ai-gateway.vercel.sh/v1"
- apiKey:  process.env.AI_GATEWAY_API_KEY
+ baseURL: "https://api.conifer.build/v1"
+ apiKey:  process.env.CONIFER_API_KEY

- baseURL: "https://openrouter.ai/api/v1"
- apiKey:  process.env.OPENROUTER_API_KEY
+ baseURL: "https://api.conifer.build/v1"
+ apiKey:  process.env.CONIFER_API_KEY

- baseURL: "https://gateway.helicone.ai/v1"
- defaultHeaders: {
-   "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
-   "Helicone-Target-URL": "https://api.openai.com",
- }
+ baseURL: "https://api.conifer.build/v1"
+ apiKey:  process.env.CONIFER_API_KEY

Some features have no equivalent. A request that uses one fails at the call site instead of silently losing the field. These are provider pinning with provider or gateway.order, prompt rewriting and transforms, moderation flags, and the image, audio, Files and Batches endpoints. Fallback lists do convert. route: "fallback" and Helicone-Fallbacks become the gateway’s own serverFallbackModels. The field-by-field matrix is cards/portability.card.json in the SDK repository.

Contributing#

The client is developed in the open at ConiferKit/use-conifer. The most useful report is an integration bug, where a client or agent does not work against the gateway when it should. Name the client, its version and the request you sent. Do not paste an API key. Both test suites run offline, with npm test and cd python && python -m pytest tests -q. TypeScript and Python stay twins, so maxCostNanoUsd is max_cost_nano_usd in Python. Costs are integer nanodollars end to end. Keys are minted in the console and are not kept in the repo.