OpenRouter 시작하기 (Quickstart)

OpenRouter는 수백 개의 AI 모델을 단일 API 엔드포인트 하나로 쓰게 해 주는 LLM 게이트웨이예요. 요청을 보내면 OpenRouter가 알아서 최적의 제공자를 고르고, 장애가 나면 자동으로 폴백까지 처리해요. 이 페이지에서는 OpenRouter를 쓰는 네 가지 방법을 하나씩 살펴볼게요.

출처: https://openrouter.ai/docs/quickstart

선택지 개요

OpenRouter를 연동하는 방법은 원하는 제어 수준에 따라 두 갈래로 나뉘어요. 딱 하나만 정확히 호출하면 되는지, 타입 안전한 호출을 원하는지, 에이전트를 만들고 싶은지에 따라 골라잡으면 돼요.

방식	어느 때 적합한가요
API	언어·프레임워크를 가리지 않고 완전한 제어가 필요할 때
Client SDKs	오버헤드를 최소화하면서 타입 안전한 모델 호출을 원할 때
Agent SDK	도구 사용·루프·상태를 갖춘 에이전트를 만들 때

예제에서 쓰는 HTTP-Referer 같은 OpenRouter 전용 헤더는 모두 선택 항목이에요. 붙여 두면 앱이 OpenRouter 리더보드에 표시될 수 있어요. 무료 모델이나 속도 제한 이야기는 FAQ를 함께 봐 주세요.

OpenRouter API 쓰기

가장 직접적인 방법이에요. /api/v1/chat/completions 엔드포인트로 표준 HTTP 요청을 보내면 돼요. 언어나 프레임워크를 가리지 않아서, 원하는 언어로 요청 골격을 만들어 주는 Request Builder를 쓰면 더 편해요.

아래 예제는 ~openai/gpt-latest 같은 latest 별칭을 쓰는데, 이건 항상 OpenAI 최신 플래그십 모델로 풀리는 별칭이에요. 모델이 새로 나와도 코드를 다시 배포할 필요가 없죠. 전체 모델 카탈로그는 openrouter.ai/models에서 둘러보거나, GET /api/v1/models 엔드포인트로 슬러그 목록을 프로그래밍 방식으로 받을 수 있어요.

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>", # 선택. openrouter.ai 랭킹용 사이트 URL
    "X-OpenRouter-Title": "<YOUR_SITE_NAME>", # 선택. openrouter.ai 랭킹용 사이트 이름
  },
  data=json.dumps({
    "model": "~openai/gpt-latest",
    "messages": [
      {
        "role": "user",
        "content": "What is the meaning of life?"
      }
    ]
  })
)

이 API는 스트리밍도 지원해요. OpenAI SDK를 OpenRouter를 가리키도록 바꾸면 그대로 드롭인 대체품으로 쓸 수도 있어요.

Client SDK 쓰기

Client SDK는 OpenRouter REST API를 타입 안전하게 감싼 얇은 층이에요. OpenAPI 스펙에서 자동 생성된 타입과 제로 상용구를 제공해서, 최소한의 오버헤드로 모델을 호출할 수 있어요.

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

const client = new OpenRouter({
  apiKey: '<OPEN...Y>',
  httpReferer: '<YOUR_SITE_URL>', // 선택
  appTitle: '<YOUR_SITE_NAME>', // 선택
});

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

if (completion instanceof ReadableStream) {
  throw new Error('Expected a non-streaming response');
}
console.log(completion.choices[0].message.content);

스트리밍, 임베딩, 전체 API 레퍼런스는 Client SDKs 문서에서 확인할 수 있어요.

Agent SDK 쓰기

Agent SDK(@openrouter/agent)는 AI 에이전트를 만들기 위한 고수준 프리미티브를 제공해요. callModel 함수 하나가 멀티 턴 대화 루프, 도구 실행, 상태 관리를 자동으로 처리해 줘요.

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

const openrouter = new OpenRouter({ apiKey: proces...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 }) => ({ temperature: 72, condition: 'sunny', location }),
});

const result = openrouter.callModel({
  model: '~anthropic/claude-sonnet-latest',
  input: 'What is the weather in San Francisco?',
  tools: [weatherTool],
});
const text = await result.getText();
console.log(text);

SDK는 프롬프트를 보내고, 모델이 도구 호출을 내놓으면 get_weather를 실행한 뒤 그 결과를 다시 주입해, 최종 응답 한 번에 callModel로 돌려줘요. 중지 조건, 스트리밍, 동적 파라미터 등은 Agent SDK 문서를 참고해 주세요.

OpenAI SDK 드롭인 사용

OpenAI SDK에 이미 짜여진 코드가 있다면, baseURL만 OpenRouter로 바꿔서 떼어 쓰는 것도 가능해요. 코드 구조를 바꾸지 않고 OpenRouter의 모델 카탈로그를 그대로 쓸 수 있는 셈이에요.

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: '<OPEN...Y>',
  defaultHeaders: {
    'HTTP-Referer': '<YOUR_SITE_URL>',
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>',
  },
});

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);

AI 어시스턴트로 빌드하기

Claude Code, Cursor, Codex 같은 AI 코딩 도구로 코드를 작성한다면, OpenRouter MCP 서버를 연결해 볼 만해요. OpenRouter가 호스팅하는 원격 서버라 설치할 게 없고, 어시스턴트가 실시간 모델/비용/크레딧 잔액 데이터와 문서를 가져와서 훈련 시점 기준이 아니라 현재 기준으로 조언해 줘요. MCP 클라이언트에 URL 하나를 추가하고 OAuth 로그인을 승인하면 끝이에요.

https://mcp.openrouter.ai/mcp

OpenRouter 시작하기 (Quickstart)