OpenRouter Quickstart Guide

OpenRouter gives you access to hundreds of AI models through a single API endpoint. It handles fallbacks automatically and picks the most cost-effective option for each request. There are three ways to integrate with OpenRouter, depending on how much control you want:

Approach	Best for
API	Full control, any language, no dependencies
Client SDKs	Type-safe model calls with minimal overhead
Agent SDK	Building agents with tool use, loops, and state

Read https://github.com/OpenRouterTeam/skills/tree/main/skills/create-agent-tui and follow the instructions to build an agent using OpenRouter.

Looking for information about free models and rate limits? Please see the FAQ

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. It works with any language or framework.

You can use the interactive Request Builder to generate OpenRouter API requests in the language of your choice.

The examples below use ~openai/gpt-latest, a latest alias that always resolves to the newest OpenAI flagship model, so your code keeps using the freshest version without redeploying. You can substitute any model slug here. Browse the full catalog at openrouter.ai/models, or list every available slug programmatically via the GET /api/v1/models endpoint.

import requests
import json

response = requests.post(
  url="https://openrouter.ai/api/v1/chat/completions",
  headers={
    "Authorization": "Bearer <OPENROUTER_API_KEY>",
    "HTTP-Referer": "<YOUR_SITE_URL>", # Optional. Site URL for rankings on openrouter.ai.
    "X-OpenRouter-Title": "<YOUR_SITE_NAME>", # Optional. Site title for rankings on openrouter.ai.
  },
  data=json.dumps({
    "model": "~openai/gpt-latest",
    "messages": [
      {
        "role": "user",
        "content": "What is the meaning of life?"
      }
    ]
  })
)

fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'HTTP-Referer': '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openrouter.ai.
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openrouter.ai.
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '~openai/gpt-latest',
    messages: [
      {
        role: 'user',
        content: 'What is the meaning of life?',
      },
    ],
  }),
});

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
  "model": "~openai/gpt-latest",
  "messages": [
    {
      "role": "user",
      "content": "What is the meaning of life?"
    }
  ]
}'

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’s intentionally lean, a thin layer over the REST API. First, install the SDK:

npm install @openrouter/sdk

pnpm add @openrouter/sdk

yarn add @openrouter/sdk

bun add @openrouter/sdk

deno add npm:@openrouter/sdk

pip install openrouter

Then use it in your code:

import { OpenRouter } from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
  httpReferer: '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openrouter.ai.
  appTitle: '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openrouter.ai.
});

const completion = await client.chat.send({
  model: '~openai/gpt-latest',
  messages: [
    {
      role: 'user',
      content: 'What is the meaning of life?',
    },
  ],
});

console.log(completion.choices[0].message.content);

from openrouter import OpenRouter
import os

with OpenRouter(api_key=os.getenv("OPENROUTER_API_KEY")) as client:
    response = client.chat.send(
        model="~openai/gpt-latest",
        messages=[
            {"role": "user", "content": "What is the meaning of life?"}
        ],
    )

    print(response.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

pnpm add @openrouter/agent

yarn add @openrouter/agent

bun add @openrouter/agent

deno add npm:@openrouter/agent

Build an agent with tools:

import { OpenRouter, tool } from '@openrouter/agent';
import { z } from 'zod';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const weatherTool = tool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name'),
  }),
  execute: async ({ location }) => {
    return { temperature: 72, condition: 'sunny', location };
  },
});

const result = openrouter.callModel({
  model: '~anthropic/claude-sonnet-latest',
  messages: [
    { role: 'user', content: 'What is the weather in San Francisco?' },
  ],
  tools: [weatherTool],
});

const text = await result.getText();
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.

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: '<OPENROUTER_API_KEY>',
  defaultHeaders: {
    'HTTP-Referer': '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openrouter.ai.
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openrouter.ai.
  },
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: '~openai/gpt-latest',
    messages: [
      {
        role: 'user',
        content: 'What is the meaning of life?',
      },
    ],
  });

  console.log(completion.choices[0].message);
}

main();

from openai import OpenAI

client = OpenAI(
  base_url="https://openrouter.ai/api/v1",
  api_key="<OPENROUTER_API_KEY>",
)

completion = client.chat.completions.create(
  extra_headers={
    "HTTP-Referer": "<YOUR_SITE_URL>", # Optional. Site URL for rankings on openrouter.ai.
    "X-OpenRouter-Title": "<YOUR_SITE_NAME>", # Optional. Site title for rankings on openrouter.ai.
  },
  model="~openai/gpt-latest",
  messages=[
    {
      "role": "user",
      "content": "What is the meaning of life?"
    }
  ]
)

print(completion.choices[0].message.content)

Using third-party SDKs

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

Building with an AI assistant

If you write code with an AI coding tool (Claude Code, Cursor, Codex, and others), connect the OpenRouter MCP server. It’s a remote server hosted by OpenRouter, so there’s nothing to install. Your assistant can pull live OpenRouter data (which models exist, what they cost, your credit balance, usage rankings) and search these docs while you build. That way its suggestions reflect current data instead of stale training knowledge. Add one URL to your MCP client and approve an OAuth login:

https://mcp.openrouter.ai/mcp

See the MCP server guide for per-client setup and the full tool list. To run models in your app, keep calling the OpenRouter API directly.

Overview

Models & Routing

Features

Ori

Privacy

Best Practices

Community

Quickstart

Using the OpenRouter API

Using the Client SDKs

Using the Agent SDK

Using the OpenAI SDK

Using third-party SDKs

Building with an AI assistant

​Using the OpenRouter API

​Using the Client SDKs

​Using the Agent SDK

​Using the OpenAI SDK

​Using third-party SDKs

​Building with an AI assistant

Using the OpenRouter API

Using the Client SDKs

Using the Agent SDK

Using the OpenAI SDK

Using third-party SDKs

Building with an AI assistant