AI Model Access

Access 400+ AI models through a single API — GPT-4, Claude, Gemini, Llama, and more — without managing separate accounts or API keys.

Quick Example

import { createFetch } from "@sapiom/fetch";

const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  agentName: "my-agent",
});

const response = await sapiomFetch(
  "https://openrouter.services.sapiom.ai/v1/chat/completions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "openai/gpt-4o-mini",
      messages: [{ role: "user", content: "Hello, world!" }],
      max_tokens: 100,
    }),
  }
);

const data = await response.json();
console.log(data.choices[0].message.content);

How It Works

Sapiom routes requests through OpenRouter, which provides unified access to AI models from all major providers. The SDK handles payment negotiation automatically — you pay per token based on the model you use.

The API is OpenAI-compatible, so you can use familiar patterns:

• Standard chat completions format
• System, user, and assistant message roles
• Temperature, top_p, and other generation parameters
• Function/tool calling (on supported models)
• JSON mode for structured outputs

You authorize a maximum cost based on max_tokens, but only pay for actual tokens generated.

Provider

Powered by OpenRouter. OpenRouter aggregates 400+ models from OpenAI, Anthropic, Google, Meta, Mistral, and others.

API Reference

Chat Completions

Endpoint: POST https://openrouter.services.sapiom.ai/v1/chat/completions

Create a chat completion using any supported model.

Request

Parameter	Type	Required	Description
model	string	Yes	Full model name with provider (e.g., openai/gpt-4o-mini)
messages	array	Yes	Array of message objects with role and content
max_tokens	number	No	Maximum tokens to generate (default: 4096, used for cost calculation)
temperature	number	No	Sampling temperature (0-2)
top_p	number	No	Nucleus sampling (0-1)
frequency_penalty	number	No	Frequency penalty (-2 to 2)
presence_penalty	number	No	Presence penalty (-2 to 2)
stop	string[]	No	Stop sequences
tools	array	No	Tool definitions for function calling
response_format	object	No	{ "type": "json_object" } for JSON mode

{
  "model": "openai/gpt-4o-mini",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is TypeScript?" }
  ],
  "max_tokens": 500,
  "temperature": 0.7
}

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "TypeScript is a strongly typed programming language..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

Price Estimate

Endpoint: POST https://openrouter.services.sapiom.ai/v1/chat/completions/price

Get a price estimate without executing the request.

const { data } = await client.post(
  "https://openrouter.services.sapiom.ai/v1/chat/completions/price",
  {
    model: "openai/gpt-4o-mini",
    messages: [{ role: "user", content: "Hello!" }],
    max_tokens: 100,
  }
);

console.log(`Maximum cost: ${data.price}`);

Response:

{
  "price": "$0.000025",
  "currency": "USD",
  "model": "openai/gpt-4o-mini",
  "estimatedInputTokens": 10,
  "maxOutputTokens": 100,
  "scheme": "upto"
}

Anthropic Messages

Endpoint: POST https://openrouter.services.sapiom.ai/v1/messages

Use the Anthropic Messages API format. Accepts the same structure as the Anthropic API — the gateway translates it for OpenRouter automatically.

{
  "model": "anthropic/claude-3.5-sonnet",
  "max_tokens": 500,
  "messages": [
    { "role": "user", "content": "Explain TypeScript generics" }
  ]
}

Price estimate: POST https://openrouter.services.sapiom.ai/v1/messages/price

OpenAI Responses

Endpoint: POST https://openrouter.services.sapiom.ai/v1/responses

Use the OpenAI Responses API format. Accepts the same structure as the OpenAI Responses API.

Price estimate: POST https://openrouter.services.sapiom.ai/v1/responses/price

Embeddings

Endpoint: POST https://openrouter.services.sapiom.ai/v1/embeddings

Generate vector embeddings from text input.

{
  "model": "openai/text-embedding-3-small",
  "input": "The quick brown fox jumps over the lazy dog"
}

Price estimate: POST https://openrouter.services.sapiom.ai/v1/embeddings/price

List Models

Endpoint: GET https://openrouter.services.sapiom.ai/v1/models

List all available models and their pricing. This endpoint is free and requires no payment.

Supported Models

OpenRouter provides access to 400+ models. Here are some popular options:

Provider	Models
OpenAI	openai/gpt-4o, openai/gpt-4o-mini, openai/gpt-4-turbo
Anthropic	anthropic/claude-3.5-sonnet, anthropic/claude-3-opus
Google	google/gemini-pro, google/gemini-flash
Meta	meta-llama/llama-3.1-405b, meta-llama/llama-3.2-90b
Mistral	mistralai/mistral-large, mistralai/mixtral-8x7b

See the OpenRouter Models page for the full list and pricing.

Complete Example

import { createFetch } from "@sapiom/fetch";

const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  agentName: "my-agent",
});

const baseUrl = "https://openrouter.services.sapiom.ai/v1";

async function chat(userMessage: string) {
  const response = await sapiomFetch(`${baseUrl}/chat/completions`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "openai/gpt-4o-mini",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: userMessage },
      ],
      max_tokens: 500,
      temperature: 0.7,
    }),
  });

  const data = await response.json();
  return data.choices[0].message.content;
}

// Usage
const response = await chat("Explain quantum computing in simple terms");
console.log(response);

Using with Third-Party SDKs

Many developers use third-party SDKs (Vercel AI SDK, OpenAI Node client, LangChain) with OpenAI-compatible endpoints. These SDKs don’t handle x402 payment natively, but all accept a custom fetch parameter. The fix is a one-liner:

Vercel AI SDK

import { createOpenAI } from "@ai-sdk/openai";
import { createFetch } from "@sapiom/fetch";

const openai = createOpenAI({
  baseURL: "https://openrouter.services.sapiom.ai/v1",
  apiKey: "unused", // x402 handles auth
  fetch: createFetch({
    apiKey: process.env.SAPIOM_API_KEY,
    agentName: "my-agent",
  }),
});

// Use as normal
const result = await generateText({
  model: openai("openai/gpt-4o-mini"),
  prompt: "Hello!",
});

OpenAI Node

import OpenAI from "openai";
import { createFetch } from "@sapiom/fetch";

const client = new OpenAI({
  baseURL: "https://openrouter.services.sapiom.ai/v1",
  apiKey: "unused",
  fetch: createFetch({
    apiKey: process.env.SAPIOM_API_KEY,
    agentName: "my-agent",
  }),
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
  max_tokens: 100,
});

LangChain

import { ChatOpenAI } from "@langchain/openai";
import { createFetch } from "@sapiom/fetch";

const model = new ChatOpenAI({
  configuration: {
    baseURL: "https://openrouter.services.sapiom.ai/v1",
    fetch: createFetch({
      apiKey: process.env.SAPIOM_API_KEY,
      agentName: "my-agent",
    }),
  },
  modelName: "openai/gpt-4o-mini",
  maxTokens: 100,
});

Or use the dedicated Sapiom LangChain integration:

import { ChatSapiom } from "@sapiom/langchain";

const model = new ChatSapiom({
  apiKey: process.env.SAPIOM_API_KEY,
  model: "openai/gpt-4o-mini",
  agentName: "my-agent",
});

Tip

The pattern works with any SDK that accepts a fetch parameter — the Sapiom fetch wrapper handles x402 payment headers transparently.

Error Codes

Code	Description
400	Invalid request — check model name and parameters
402	Payment required — ensure you’re using the Sapiom SDK
404	Model not found — use full model name with provider prefix
429	Rate limit exceeded

Common Issues

Missing max_tokens: The gateway requires max_tokens to calculate maximum cost:

// Wrong — missing max_tokens
{ model: "openai/gpt-4o-mini", messages: [...] }

// Correct
{ model: "openai/gpt-4o-mini", messages: [...], max_tokens: 100 }

Model not found: Use the full model name with provider prefix:

// Wrong
{ model: "gpt-4o-mini" }

// Correct
{ model: "openai/gpt-4o-mini" }

Pricing

Pricing varies by model and is based on token usage:

• Input tokens: Cost per 1M tokens (varies by model)
• Output tokens: Cost per 1M tokens (varies by model)

The gateway uses an “upto” payment scheme — you authorize maximum cost based on max_tokens, but only pay for tokens actually generated.

See OpenRouter Pricing for per-model rates.