OpenRouter 연동을 다른 API Gateway로 마이그레이션하는 방법

먼저 migration 시나리오 선택하기

• 현재 integration, billing path, model availability, operational behavior가 애플리케이션 요구사항을 충족하면 OpenRouter 유지를 선택합니다.
• primary integration을 바꿀 필요는 없지만 두 번째 route가 유용하다면 검증된 backup 추가를 선택합니다.
• 후보 gateway가 protocol과 model requirement를 충족하고 통제된 traffic에서 실제 behavior를 비교할 준비가 되었다면 migration canary 실행을 선택합니다.

BetterToken은 OpenRouter 계정을 판매하지 않으며 OpenRouter key나 balance를 이전할 수 없습니다. 테스트하려면 본인의 BetterToken 계정과 API Key를 만들고 Workspace 또는 현재 문서에서 최신 Model ID와 key requirement를 확인하세요.

configuration을 건드리기 전에 requirements matrix 만들기

“OpenAI-compatible”은 service의 전체 behavior가 아니라 interface 일부를 설명합니다. 두 gateway가 비슷한 요청을 받을 수 있어도 available model, streaming event, tool-call payload, error body, retry header, rate limit, usage accounting은 서로 다를 수 있습니다.

후보를 테스트하기 전에 각 requirement의 현재 behavior와 acceptance criterion을 기록하세요.

model count만으로 gateway를 선택하지 마세요. 중요한 것은 현재 필요한 Model ID와 response contract가 이 애플리케이션에서 작동하는지입니다. 모델 제공 여부와 가격은 동적이므로 migration 시점에 provider의 현재 catalog와 rate card를 읽으세요.

시나리오 1: OpenRouter 유지하기

해결해야 할 구체적인 gap이 없다면 그대로 유지하세요. 애플리케이션이 OpenRouter의 현재 catalog, routing, header, response behavior에 의존한다면 migration은 상응하는 benefit 없이 새로운 failure mode를 만듭니다.

향후 portability는 미리 준비할 수 있습니다.

• Base URL, API Key, Model ID를 configuration으로 이동합니다.
• 애플리케이션이 사용하는 response와 error field를 문서화합니다.
• provider-specific header를 shared request logic에서 분리합니다.
• 격리된 key로 실행할 수 있는 contract test를 추가합니다.
• rollback owner와 허용되는 retry policy를 기록합니다.

이 작업은 지금 production traffic을 바꾸지 않으면서 이후 migration risk를 낮춥니다.

시나리오 2: 검증된 backup 추가하기

backup route는 primary route와 동일한 contract test를 통과한 후에만 유용합니다. provider configuration을 분리해 유지하고, 다른 요청이 성공한다는 사실만 증명하기 위해 OpenRouter setting을 덮어쓰지 마세요.

어떤 failure가 fallback 대상인지 정확히 정의하세요. authentication failure, invalid Model ID, unsupported method, malformed request와 대부분의 다른 client error는 다른 provider를 통해 자동 retry해서는 안 됩니다. transient failure에서도 fallback은 idempotency, retry limit, timeout budget, 후보의 feature support 범위 안에서만 허용됩니다.

애플리케이션에 검증된 idempotency mechanism이 있고 destination state를 확인할 수 있는 경우가 아니라면 같은 mutating operation을 두 gateway로 보내지 마세요. backup이 모든 요청의 완료나 동일한 output을 보장하지는 않습니다.

시나리오 3: canary로 마이그레이션하기

후보가 isolated test를 통과했고 primary route를 옮기는 것이 목표일 때 canary를 사용하세요. 처음에는 중요하지 않은 traffic의 작고 통제된 segment만 전송합니다. observation window와 rollback check가 끝날 때까지 현재 route를 유지하세요.

canary를 시작하기 전에 success를 정의합니다.

• expected response schema를 fallback code 없이 parse합니다.
• 필요한 streaming과 tool-call behavior가 통과합니다.
• error type을 계속 분류할 수 있습니다.
• usage record가 애플리케이션에서 허용한 boundary 안에서 reconcile됩니다.
• latency, timeout, retry behavior가 정의된 threshold를 충족합니다.
• duplicated 또는 missing side effect가 없습니다.

필수 condition 하나라도 실패하면 확장을 멈추고 새 traffic을 known-good configuration으로 돌리세요.

5단계 migration procedure

1단계: 현재 contract inventory 작성하기

정확한 protocol, SDK와 method, OpenRouter Base URL, Model ID, authentication variable, provider-specific header, streaming mode, tool use, timeout policy, retry policy, error field, request ID, usage field를 기록하세요.

어떤 항목이 hard requirement이고 어떤 항목은 변경 가능한지 구분하세요. logging field는 바꿀 수 있지만 production automation에서 사용하는 tool-call contract는 바꾸기 어려울 수 있습니다.

API Key를 worksheet에 복사하지 마세요. secret의 variable name과 storage location만 기록합니다.

2단계: 격리된 후보 configuration 만들기

후보 gateway에서 별도 test key를 만드세요. production key를 재사용하거나 secret을 repository에 commit하지 마세요.

BetterToken에서는 본인의 계정을 사용하고 Workspace 또는 현재 API documentation에 표시된 최신 Model ID와 key requirement를 선택합니다. 오래된 tutorial의 Model ID를 hardcode하지 마세요.

후보 configuration은 현재 OpenRouter configuration을 덮지 말고 나란히 유지하세요. 이 분리가 comparison과 rollback을 가능하게 합니다.

3단계: protocol-specific Base URL 설정하기

OpenAI-compatible BetterToken 클라이언트에서는 다음을 사용합니다.

TEST_API_KEY=your_test_api_key_here
TEST_BASE_URL=https://www.bettertoken.ai/v1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-088&utm_content=analog-openrouter-v-rossii-vybor-i-perenos-api
TEST_MODEL_ID=current_model_id_from_provider_catalog

Anthropic-compatible 클라이언트에서 BetterToken Base URL은 /v1이 없는 https://bettertoken.ai입니다. Anthropic-compatible 클라이언트에 OpenAI-compatible Python request shape를 재사용하지 말고 해당 경로의 SDK와 protocol documentation을 따르세요.

클라이언트가 versioned Base URL을 요구하는지, 또는 path 일부를 직접 추가하는지 확인하세요. /v1이 중복되거나 빠진 것은 configuration error이며 전체 gateway가 unavailable하다는 evidence가 아닙니다.

4단계: 동일한 minimal request와 contract test 실행하기

애플리케이션과 동일한 SDK family와 method를 사용하세요. 다음 Python 예시는 환경 변수를 사용해 OpenAI-compatible Chat Completions 요청을 테스트합니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TEST_API_KEY"],
    base_url=os.environ["TEST_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["TEST_MODEL_ID"],
    messages=[{"role": "user", "content": "Reply with: gateway test passed"}],
    max_tokens=32,
)

print(response.choices[0].message.content)
print(response.usage)

placeholder는 의도적으로 남겨 둔 것입니다. 실제 key는 project의 secret mechanism을 통해 불러오고, 현재 Model ID는 test 시점에 provider에서 가져오세요.

basic request 이후 production application이 해당 behavior에 의존한다면 streaming, tool call, invalid authentication, invalid Model ID를 각각 테스트하세요. timestamp, status, 가능한 경우 request ID, response shape, usage field, application result처럼 민감하지 않은 evidence를 기록합니다.

5단계: canary 전송, 비교, 결정하기

중요하지 않은 traffic의 통제된 일부를 후보로 route합니다. 대표 observation window 동안 두 route를 비교하세요.

• success와 classified error count
• latency distribution과 timeout behavior
• retry count와 존재하는 경우 Retry-After handling
• response와 tool-call schema
• streaming completion
• input, cached input, output usage
• provider-side status와 charge record
• duplicated, missing, delayed side effect

모든 hard requirement가 통과한 뒤에만 확장하세요. rollback trigger가 발생하면 새 traffic을 OpenRouter로 돌리고 후보를 offline에서 조사합니다.

성공한 response 이상의 항목 검증하기

성공한 HTTP status는 요청 하나가 반환되었다는 사실만 증명합니다. protocol equivalence, production readiness, correct routing을 증명하지는 않습니다.

error를 의도적으로 검증하기

격리된 test key로 controlled failure를 일으키세요.

• invalid Model ID
• revoke했거나 의도적으로 invalid한 test key
• 안전하게 테스트할 수 있는 unsupported method
• non-production environment의 timeout

HTTP status, error body, request ID, retry metadata, client behavior를 확인하세요. terminal error가 무한 retry되지 않도록 하고 log에서 credential과 민감한 request content가 제거되는지 확인합니다.

OpenRouter error reference는 OpenRouter의 behavior를 설명합니다. 후보의 현재 documentation과 관찰한 response는 별도 contract로 다루세요.

usage 대조하기

SDK에 반환된 usage object를 캡처해 application log와 provider account record에 비교하세요. 필요한 field에는 input token, cached input, output token 또는 provider-specific unit이 포함될 수 있습니다.

BetterToken Dashboard는 request time, model, status, input, output, cache token, corresponding charge를 표시할 수 있습니다. complete prompt나 response를 저장하거나 표시한다는 의미는 아닙니다. test time과 다른 비밀이 아닌 metadata로 record를 맞추고, 성공한 reply가 어느 route에서 처리되었는지 증명한다고 가정하지 마세요.

streaming과 tool call을 별도로 테스트하기

streaming에서는 first event, content delta, finish reason, 제공되는 경우 final usage, disconnect handling, partial answer와 completed answer를 애플리케이션이 구분할 수 있는지를 검증합니다.

tool call에서는 tool name, call ID, serialized argument, validation failure, result submission flow를 비교하세요. 첫 test에서는 read-only tool을 사용합니다. 정상적인 text response만으로 tool-call path가 compatible하다고 증명할 수는 없습니다.

Rollback 경계

canary를 시작하기 전에 rollback을 명시적이고 reversible하게 만드세요.

다음과 같은 hard requirement failure가 발생하면 즉시 rollback합니다.

• 애플리케이션이 response 또는 error schema를 parse하지 못합니다.
• 필수 stream이 incomplete하게 끝납니다.
• tool-call argument 또는 ID가 손상됩니다.
• 필수 billing control에 필요한 usage를 reconcile할 수 없습니다.
• timeout 또는 error behavior가 합의한 operational threshold를 넘습니다.
• mutating workflow가 outcome이 불분명하거나 duplicated 또는 missing인 result를 만듭니다.

rollback할 때:

1. candidate traffic 확장을 중지합니다.
2. 새 request를 known-good OpenRouter configuration으로 보냅니다.
3. outcome을 알 수 없는 mutating request를 자동 replay하지 않습니다.
4. diagnosis를 위해 timestamp, request ID, status code, redacted log를 보존합니다.
5. 원인을 이해할 때까지 candidate key를 격리해 두고, 더 이상 필요하지 않으면 revoke합니다.

migration owner가 observation window, rollback test, downstream reconciliation을 확인하기 전에는 old configuration이나 credential을 삭제하지 마세요. 두 route를 모두 활성 상태로 유지한다면 ownership, health check, eligible fallback error, maximum retry budget을 문서화하세요.

비용과 운영 점검

migration runbook에 fixed price를 넣지 마세요. test date에 각 provider의 현재 rate card를 읽고 실제 기록된 usage와 비교합니다.

다음 항목을 decision에 포함하세요.

• model과 feature availability
• input, cached input, output rate
• payment 시점에 표시되는 minimum funding 또는 account requirement
• request와 concurrency limit
• timeout과 retry behavior
• usage export 또는 Dashboard visibility
• key rotation과 per-project control
• support와 incident escalation path

BetterToken에서는 오래된 screenshot이나 복사된 rate 대신 현재 pricing page와 Workspace를 사용하세요. BetterToken은 하나의 candidate gateway일 뿐이며 모든 OpenRouter workload가 변경 없이 migrate할 수 있다는 증거가 아닙니다.

최종 decision checklist

다음에 해당하면 OpenRouter를 유지합니다.

• 구체적인 integration 또는 operational gap이 없습니다.
• 현재 catalog와 contract가 필요합니다.
• 후보가 hard requirement를 통과하지 못했습니다.

다음에 해당하면 backup을 추가합니다.

• 두 번째 route가 독립적인 value를 가집니다.
• 동일한 protocol, error, usage, feature test를 통과했습니다.
• fallback rule이 bounded하고 observable합니다.

다음에 해당하면 migrate합니다.

• 후보가 모든 hard requirement를 충족합니다.
• canary가 허용된 error와 latency threshold 안에 유지됩니다.
• usage와 billing record가 reconcile됩니다.
• rollback을 테스트했고 여전히 작동합니다.

OpenAI-compatible label은 test plan의 시작이지 완전한 equivalence의 증거가 아닙니다. 가장 안전한 migration은 isolated, observable, incremental, reversible합니다.

BetterToken이 integration 후보라면 현재 API documentation부터 확인하고 별도 test key를 만든 뒤 production traffic을 바꾸기 전에 5단계 canary를 실행하세요.

Sources

• OpenRouter quickstart
• OpenRouter errors and debugging
• OpenRouter model catalog
• BetterToken API reference