모델 폴백 (Model Fallbacks)

주 모델의 제공자가 다운됐거나 속도 제한에 걸리거나, 콘텐츠 검열로 응답을 거부할 때 다른 모델로 자동 시도하게 하는 게 모델 폴백이에요. models 파라미터에 우선순위 순으로 모델 ID 배열을 넣으면, 첫 모델이 에러를 내면 OpenRouter가 다음 모델로 넘어가요.

출처: https://openrouter.ai/docs/guides/routing/model-fallbacks

동작 방식

models 배열에 모델 ID를 우선순위 순으로 넣어요. 아래 예시는 ~anthropic/claude-sonnet-latest를 먼저 시도하고, 실패하면 gryphe/mythomax-l2-13b를 시도해요.

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

const openRouter = new OpenRouter({ apiKey: '<OPEN...Y>' });

const completion = await openRouter.chat.send({
  chatRequest: {
    models: ['~anthropic/claude-sonnet-latest', 'gryphe/mythomax-l2-13b'],
    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);

폴백 동작

선택한 모델이 에러를 반환하면 OpenRouter는 폴백 모델을 시도해요. 폴백 모델마저 다운됐거나 에러를 내면 그 에러를 그대로 돌려줘요. 기본적으로 어떤 에러든 폴백 트리거가 될 수 있어요.

컨텍스트 길이 검증 에러
필터링된 모델에 대한 검열 플래그
속도 제한 (rate-limiting)
다운타임

가격

요청은 결국 사용된 모델 기준으로 과금돼요. 그 모델은 응답 본문의 model 속성으로 확인할 수 있어요.

Anthropic Messages API에서 쓰기

Anthropic Messages API 엔드포인트(/api/v1/messages)는 fallbacks 파라미터를 받아요. Anthropic SDK가 쓰는 형태와 같죠. 각 항목은 순서대로 시도할 폴백 모델을 지정해요. 이 목록은 OpenRouter의 models 라우팅으로 매핑되어, 위에서 본 것과 같은 에러(속도 제한, 다운타임, 검열 거부)에서 폴백이 발동돼요 — 단순 거부만이 아니라요.

이 폴백 라우팅은 OpenRouter가 직접 처리해요. fallbacks 파라미터는 Anthropic의 서버 측 폴백 기능을 쓰지 않아요.

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  baseURL: 'https://openrouter.ai/api',
  apiKey: '<OPEN...Y>',
});

const message = await anthropic.beta.messages.create({
  model: 'anthropic/claude-sonnet-4.5',
  max_tokens: 1024,
  fallbacks: [{ model: 'anthropic/claude-opus-4.1' }],
  messages: [{ role: 'user', content: 'What is the meaning of life?' }],
});

제한 사항

각 fallbacks 항목은 model 필드만 허용해요. max_tokens, thinking, speed, output_config 같은 시도별 재정의는 400 에러로 거부돼요.
fallbacks는 models 파라미터와 함께 쓸 수 없어요. 둘 다 보내면 400 에러가 나요.
fallbacks는 최대 3개 항목까지 받아요. 더 긴 목록은 400 에러예요.

OpenAI SDK와 함께 쓰기

OpenAI SDK로 models 배열을 쓰려면 extra_body에 포함하면 돼요. 아래 예시에서는 ~openai/gpt-latest가 먼저 시도되고, models 배열이 순서대로 폴백으로 시도돼요.

모델 폴백 (Model Fallbacks)