# AI Model Access

Access 400+ AI models through a single API

## Navigation

**Getting Started:** [All You Need](/index.md) | [Getting Started](/introduction.md) | [How Sapiom Works](/how-it-works.md) | [Quick Start](/quick-start.md) | [Using Services](/using-services.md) | [For AI Tools](/for-agents.md)  
**Capabilities:** [Overview](/capabilities.md) | [Verify Users](/capabilities/verify.md) | [Search the Web](/capabilities/search.md) | **AI Model Access** | [Generate Images](/capabilities/images.md) | [Audio Services](/capabilities/audio.md) | [Browser Automation](/capabilities/browser.md)  
**Integration / Agent Frameworks:** [Overview](/integration/agent-frameworks.md) | [LangChain](/integration/agent-frameworks/langchain.md) | [LangChain Classic](/integration/agent-frameworks/langchain-classic.md)  
**Integration / HTTP Clients:** [Overview](/integration/http-clients.md) | [Axios](/integration/http-clients/axios.md) | [Fetch](/integration/http-clients/fetch.md) | [Node.js HTTP](/integration/http-clients/node-http.md)  
**Governance:** [Overview](/governance.md) | [Setting Up Rules](/governance/rules.md) | [Agents & Identity](/governance/agents.md) | [Activity](/governance/activity.md)  
**Reference / API Reference:** [Introduction](/api-reference/introduction.md)  
**Reference / API Reference / Endpoints:** [Agents Endpoints](/api-reference/endpoints/agents.md) | [Get agent by ID](/api-reference/endpoints/agents/v1-agents-by-id-get.md) | [Update agent](/api-reference/endpoints/agents/v1-agents-by-id-patch.md) | [List all agents](/api-reference/endpoints/agents/v1-agents-get.md) | [Create a new agent](/api-reference/endpoints/agents/v1-agents-post.md) | [API Endpoints](/api-reference/endpoints.md) | [Get Sapiom payment JWKS](/api-reference/endpoints/other/.well-known-sapiom-jwks.json-get.md) | [Analytics Endpoints](/api-reference/endpoints/other.md) | [Get analytics chart](/api-reference/endpoints/other/v1-analytics-chart-get.md) | [Get analytics leaderboards](/api-reference/endpoints/other/v1-analytics-leaderboards-get.md) | [Get analytics summary](/api-reference/endpoints/other/v1-analytics-summary-get.md) | [Rules Endpoints](/api-reference/endpoints/rules.md) | [Get rule by ID](/api-reference/endpoints/rules/v1-spending-rules-by-id-get.md) | [Update a rule](/api-reference/endpoints/rules/v1-spending-rules-by-ruleId-put.md) | [List all rules](/api-reference/endpoints/rules/v1-spending-rules-get.md) | [Create a new rule](/api-reference/endpoints/rules/v1-spending-rules-post.md) | [Transactions Endpoints](/api-reference/endpoints/transactions.md) | [Complete a transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-complete-post.md) | [List transaction costs](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-get.md) | [Add cost to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-post.md) | [Add facts to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-facts-post.md) | [Get transaction details](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-get.md) | [Reauthorize a transaction with x402 payment data](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-reauthorize-post.md) | [List transactions](/api-reference/endpoints/transactions/v1-transactions-get.md) | [Create a new transaction](/api-reference/endpoints/transactions/v1-transactions-post.md) | [Verification Endpoints](/api-reference/endpoints/verification.md) | [Check verification code](/api-reference/endpoints/verification/v1-services-verify-check-post.md) | [Send verification code](/api-reference/endpoints/verification/v1-services-verify-send-post.md)  
**Reference / SDK Reference:** [@sapiom/axios](/reference/sdk/axios.md) | [@sapiom/fetch](/reference/sdk/fetch.md) | [SDK Reference](/reference/sdk.md) | [@sapiom/langchain-classic](/reference/sdk/langchain-classic.md) | [@sapiom/langchain](/reference/sdk/langchain.md) | [@sapiom/node-http](/reference/sdk/node-http.md)  
**Reference:** [Concepts](/reference/concepts.md)

---

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

## Quick Example

```typescript

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](https://openrouter.ai), 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](https://openrouter.ai). 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 |

```json
{
  "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

```json
{
  "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.

```typescript
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:

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](https://openrouter.ai/docs#models) page for the full list and pricing.

## Complete Example

```typescript

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:**
```typescript
    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:**
```typescript
    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:**
```typescript
    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:

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

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

> 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:

```typescript
// 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:

```typescript
// 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](https://openrouter.ai/docs#models) for per-model rates.