Quickstart

OpenRouter provides a unified API that gives you access to hundreds of AI models through a single endpoint, while automatically handling fallbacks and selecting the most cost-effective options.

There are three ways to integrate with OpenRouter, depending on how much control you want:

Read https://openrouter.ai/skills/create-agent/SKILL.md and follow the instructions to build an agent using OpenRouter.

In the examples below, the OpenRouter-specific headers are optional. Setting them allows your app to appear on the OpenRouter leaderboards. For detailed information about app attribution, see our App Attribution guide.

Using the OpenRouter API

The most direct way to use OpenRouter. Send standard HTTP requests to the /api/v1/chat/completions endpoint — compatible with any language or framework.

1
import requests
2
import json
3
4
response = requests.post(
5
  url="https://openrouter.ai/api/v1/chat/completions",
6
  headers={
7
    "Authorization": "Bearer <OPENROUTER_API_KEY>",
8
    "HTTP-Referer": "<YOUR_SITE_URL>", # Optional. Site URL for rankings on openrouter.ai.
9
    "X-OpenRouter-Title": "<YOUR_SITE_NAME>", # Optional. Site title for rankings on openrouter.ai.
10
  },
11
  data=json.dumps({
12
    "model": "openai/gpt-5.2",
13
    "messages": [
14
      {
15
        "role": "user",
16
        "content": "What is the meaning of life?"
17
      }
18
    ]
19
  })
20
)

The API also supports streaming. You can also use the OpenAI SDK pointed at OpenRouter as a drop-in replacement.

Using the Client SDKs

The Client SDKs wrap the OpenRouter API with full type safety, auto-generated types from the OpenAPI spec, and zero boilerplate. It is intentionally lean — a thin layer over the REST API.

First, install the SDK:

$
npm install @openrouter/sdk

Then use it in your code:

1
import OpenRouter from '@openrouter/sdk';
2
3
const client = new OpenRouter({
4
  apiKey: '<OPENROUTER_API_KEY>',
5
  defaultHeaders: {
6
    'HTTP-Referer': '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openrouter.ai.
7
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openrouter.ai.
8
  },
9
});
10
11
const completion = await client.chat.send({
12
  model: 'openai/gpt-5.2',
13
  messages: [
14
    {
15
      role: 'user',
16
      content: 'What is the meaning of life?',
17
    },
18
  ],
19
});
20
21
console.log(completion.choices[0].message.content);

See the full Client SDKs documentation for streaming, embeddings, and the complete API reference.

Using the Agent SDK

The Agent SDK (@openrouter/agent) provides higher-level primitives for building AI agents. It handles multi-turn conversation loops, tool execution, and state management automatically via the callModel function.

Install the package:

$
npm install @openrouter/agent

Build an agent with tools:

1
import { callModel, tool } from '@openrouter/agent';
2
import { z } from 'zod';
3
4
const weatherTool = tool({
5
  name: 'get_weather',
6
  description: 'Get the current weather for a location',
7
  inputSchema: z.object({
8
    location: z.string().describe('City name'),
9
  }),
10
  execute: async ({ location }) => {
11
    return { temperature: 72, condition: 'sunny', location };
12
  },
13
});
14
15
const result = await callModel({
16
  model: 'anthropic/claude-sonnet-4',
17
  messages: [
18
    { role: 'user', content: 'What is the weather in San Francisco?' },
19
  ],
20
  tools: [weatherTool],
21
});
22
23
const text = await result.getText();
24
console.log(text);

The SDK sends the prompt, receives a tool call from the model, executes get_weather, feeds the result back, and returns the final response — all in one callModel invocation.

See the full Agent SDK documentation for stop conditions, streaming, dynamic parameters, and more.

Using the OpenAI SDK

You can also use the OpenAI SDK pointed at OpenRouter as a drop-in replacement. This is useful if you have existing code built on the OpenAI SDK and want to access OpenRouter’s model catalog without changing your code structure.

1
import OpenAI from 'openai';
2
3
const openai = new OpenAI({
4
  baseURL: 'https://openrouter.ai/api/v1',
5
  apiKey: '<OPENROUTER_API_KEY>',
6
  defaultHeaders: {
7
    'HTTP-Referer': '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openrouter.ai.
8
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openrouter.ai.
9
  },
10
});
11
12
async function main() {
13
  const completion = await openai.chat.completions.create({
14
    model: 'openai/gpt-5.2',
15
    messages: [
16
      {
17
        role: 'user',
18
        content: 'What is the meaning of life?',
19
      },
20
    ],
21
  });
22
23
  console.log(completion.choices[0].message);
24
}
25
26
main();

Using third-party SDKs

For information about using third-party SDKs and frameworks with OpenRouter, please see our frameworks documentation.