OpenRouter 클라이언트용 OpenAI 호환 엔드포인트
openrouter openai compatible endpoint는 OpenAI 채팅 형식을 사용하는 base URL일 뿐이므로, 이를 다른 것으로 교체하는 데에는 몇 줄의 코드만 필요합니다. 정확한 값, 요청 형태 및 발생할 수 있는 오류는 다음과 같습니다.
업데이트

주요 포인트
- 베이스 URL은 https://api.openrouteralternativeapi.com/v1이며 모델 ID는 uncensored입니다.
- 인증은 표준 Bearer 헤더이며, POST /v1/chat/completions과 GET /v1/models만 존재합니다.
- 스트리밍, 도구 및 JSON 모드는 작동하지만 라우터 전용 필드는 지원되지 않습니다.
- HTTP 429 발생 시 오류 코드를 읽어 속도 제한과 동시성 제한을 구분하세요.
필요한 값
OpenAI 스타일 엔드포인트를 편집할 수 있는 도구에는 세 가지 값이 필요합니다. 표에서 이 값들을 복사하면 일반적인 설정에서는 다른 부분이 변경되지 않습니다.
| 설정 | 내용 |
|---|---|
| 기본 URL | https://api.openrouteralternativeapi.com/v1 |
| API 키 | API 키 페이지에서 생성됨 |
| 모델 ID | uncensored |
| 인증 헤더 | Authorization: Bearer YOUR_API_KEY |
| 채팅 경로 | POST /v1/chat/completions |
| 모델 목록 라우트 | GET /v1/models |
base URL은 이미 /v1로 끝납니다. 대부분의 SDK는 /chat/completions을 자동으로 붙이므로 중복으로 추가하지 마세요. 일부 도구는 전체 채팅 엔드포인트를 요구하기도 합니다. 이 경우 base URL에 이어지는 /chat/completions를 사용하세요.
엔드포인트의 정의와 한계
URL 뒤에는 독립적인 공급자가 실행하고 합법적인 성인 사용에 대해 콘텐츠 거부 없이 답변하도록 조정된 단일 오픈 웨이트 모델이 있습니다. 라우터가 아니므로 요청이 다른 공급자에게 전달되지 않습니다. 또한 어떤 모델 제작사의 공식 API도 아닙니다. 이는 구성에 중요합니다: 선택할 모델 슬러그 목록이 없고, 공급자 선호도 필드가 없으며, 폴백 체인도 없습니다. uncensored를 보내면 해당 모델만 얻습니다.
서비스는 텍스트 전용입니다. 이미지 생성, 오디오, 비디오, 임베딩 및 파인튜닝은 제공되지 않으므로, /v1/embeddings 또는 이미지 라우트를 호출하는 클라이언트는 이 base URL에서 실패합니다. 이러한 호출은 기존에 사용하는 서비스로 향하게 하세요. 애플리케이션이 여러 서비스를 혼합하는 경우 base URL을 전역이 아닌 기능별로 설정하세요.
호환성 관련 마지막 포인트는 모델 목록입니다. 시작 시 GET /v1/models를 호출하여 드롭다운을 채우거나 설정을 검증하는 클라이언트는 하나의 모델만 받습니다. 이는 정상입니다. 구성한 모델 이름이 목록에 있는지 확인하는 코드가 있다면 이름을 uncensored로 설정하면 확인이 통과합니다. 애플리케이션이 구성 파일 깊숙한 곳에 벤더 모델 이름을 하드코딩했다면, URL 변경 후에도 앱이 실패하는 가장 흔한 이유가 남은 문자열이기 때문에 첫 실행 전에 저장소에서 검색하세요.
첫 번째 요청, 세 가지 방법
터미널에서 요청으로 시작하세요. 이는 프레임워크가 관여하기 전에 키, URL 및 모델 ID를 증명합니다.
curl https://api.openrouteralternativeapi.com/v1/models -H "Authorization: Bearer $API_KEY"
curl https://api.openrouteralternativeapi.com/v1/chat/completions -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Reply with the word ready."}],
"max_tokens": 10
}'
Python SDK로 동일한 호출. base_url과 api_key 외에 표준 OpenAI 코드와 다른 점은 없습니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.openrouteralternativeapi.com/v1",
api_key="YOUR_API_KEY",
)
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the word ready."}],
max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)
Node를 사용하여 환경 변수에서 키 읽기:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.openrouteralternativeapi.com/v1",
apiKey: process.env.API_KEY,
});
const r = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Reply with the word ready." }],
max_tokens: 10,
});
console.log(r.choices[0].message.content);
많은 도구는 생성자 인수보다 환경 변수를 읽습니다. 공식 SDK는 일반적으로 OPENAI_BASE_URL과 OPENAI_API_KEY을 인식하므로 수정되지 않은 스크립트의 경로를 리디렉션할 수 있습니다. SDK 버전의 문서를 확인하여 이름이 정확한지 확인하세요.
스트리밍, 도구 및 JSON 모드
대부분의 클라이언트가 의존하는 기능이 있습니다. 서버 전송 이벤트를 받으려면 stream: true를 설정하세요. 사용량은 스트림 끝에 보고됩니다. 도구 호출은 tools과 tool_choice을 허용하며, tool_calls 델타를 스트리밍하고 role: "tool" 메시지로 결과를 기대합니다. JSON 모드는 response_format: {"type":"json_object"}로 활성화됩니다. 샘플링 필드 temperature, top_p, stop, seed 및 빈도 및 존재 패널티는 전달됩니다.
Python의 스트리밍 예제:
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write three short taglines for a coffee cart."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
JSON 모드도 있으며, 이는 기대하는 키를 지시하는 프롬프트 지시문과 함께 사용하는 것이 좋습니다:
r = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "Return JSON with keys title and tags (array of strings)."},
{"role": "user", "content": "Summarise: a guide to brewing cold coffee at home."},
],
response_format={"type": "json_object"},
)
print(r.choices[0].message.content)
어쨌든 try 블록에서 결과를 항상 구문 분석하세요. JSON 모드는 유효한 출력의 확률을 높이지만, 코드는 여전히 잘못된 응답을 처리해야 합니다. 예를 들어 한 번 재시도하는 방식으로 처리하세요.
다중 턴 채팅 및 도구 호출
엔드포인트는 OpenAI 채팅 라우트처럼 상태가 없습니다. 이전 호출을 기억하지 않으므로 각 요청에는 모델이 보길 원하는 대화 내용을 포함해야 합니다. 메시지 목록을 유지하고 각 턴 후에 어시스턴트 응답을 추가한 후 전체 목록을 다시 보내세요. 총계를 주의하세요: 100,000-토큰 창은 프롬프트와 완료를 포함하며, 긴 대화 기록은 입력 비용의 원인이 됩니다.
history = [{"role": "system", "content": "You answer in two sentences."}]
def chat(text):
history.append({"role": "user", "content": text})
r = client.chat.completions.create(model="uncensored", messages=history)
reply = r.choices[0].message.content
history.append({"role": "assistant", "content": reply})
return reply
도구 호출의 경우, tools에 함수를 설명하고, 모델이 요청한 것을 실행한 후, 일치하는 tool_call_id을 가진 role: "tool" 메시지로 출력을 보내세요. 최소한의 정의는 다음과 같습니다:
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up an order by its number",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Where is order 1042?"}],
tools=tools,
tool_choice="auto",
)
call = r.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
실행 전에 인수를 검증하세요. 모델이 호출을 제안합니다. 함수가 돈, 파일 또는 타인의 데이터에 접근할 때 특히, 실행이 안전한지 여부를 코드에서 결정해야 합니다.
OpenRouter 스타일 요청에서 제거할 필드
라우터용으로 작성된 클라이언트는 종종 요청 본문 또는 헤더에 추가 항목을 추가합니다. 일반적인 예로는 공급자 순서, 모델 폴백 배열, 라우팅 선호도 및 속성 헤더가 있습니다. 이 API는 이를 사용하지 않습니다. 알 수 없는 필드는 무시되거나 오류를 발생시킬 수 있으므로, 두 결과 모두에 의존하기보다는 제거하세요.
- 공급사 접두사가 포함된 모든 모델 슬러그를
uncensored로 교체하세요. - 폴백 목록을 제거하세요. 단일 모델을 사용할 수 없는 경우 자체 재시도 로직으로 처리하세요.
- 이미지 또는 오디오 콘텐츠 부분을 보내지 마세요. 모델은 텍스트를 읽습니다.
- 전체 요청 본문을 8 MB 이하로 유지하세요.
docs 페이지는 지원되는 매개변수를 보여주며, 필드가 클라이언트가 기대하는 것과 다르게 동작할 때 확인해야 할 곳입니다.
제한 사항 및 429 응답
풀 키는 동시 8개 요청과 분당 300개 요청을 허용합니다. 체험 키는 각각 2개와 60개를 허용합니다. 각 응답에는 X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests 및 X-RateLimit-Limit-Concurrency이 포함됩니다. 모든 실패 시 요청 ID를 로그에 기록하세요. 지원팀이 가장 먼저 요청하는 것이 바로 이 ID이기 때문입니다.
HTTP 429에는 세 가지 종류가 있습니다. 오류 코드 rate_limited은 분당 요청 수를 초과했음을 의미합니다: 속도를 늦추세요. 코드 concurrency은 동시에 너무 많은 요청이 진행 중임을 의미합니다: 큐에 넣으세요. Retry-After: 5 헤더가 있는 429는 일시적 과부하를 의미합니다: 5초를 기다렸다가 다시 시도하세요. 스트리밍 요청은 스트림이 끝날 때까지 동시성 슬롯을 유지하므로, 끝까지 읽지 않고 중단된 클라이언트는 용량을 소모할 수 있습니다.
import time
from openai import OpenAI, RateLimitError
client = OpenAI(
base_url="https://api.openrouteralternativeapi.com/v1",
api_key="YOUR_API_KEY",
max_retries=0,
)
def ask(prompt, tries=4):
for i in range(tries):
try:
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
except RateLimitError as e:
wait = 5 if i == 0 else 5 * (i + 1)
time.sleep(wait)
raise RuntimeError("still rate limited")
워커를 병렬로 실행하는 경우 호출 주변에 8개 이하의 값을 가진 세마포어를 설정하세요. 이는 오류로부터 제한을 학습하는 것보다 저렴합니다. 함께 실패한 여러 워커가 같은 초에 모두 재시도하지 않도록 대기 시간에 약간의 무작위 지터를 추가하세요. 낮은 트래픽에서도 반복적인 429 응답이 보이면 열렸지만 닫히지 않은 스트림이나 기다림 없이 트리거되는 재시도 루프를 찾아보세요. 이러한 요소들 중 하나가 사용 가능한 슬롯을 모두 채울 수 있기 때문입니다.
프로덕션 적용 전 비용 확인
가격은 선불 크레딧 기준 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50입니다. 입력 토큰 2,000개와 출력 토큰 500개를 가진 요청을 가져옵니다. 입력 비용은 2,000 / 1,000,000 x $0.15 = $0.0003입니다. 출력 비용은 500 / 1,000,000 x $0.50 = $0.00025입니다. 요청 비용은 $0.00055이며, 따라서 1,000개의 이러한 요청 비용은 $0.55입니다. 실패하거나 거부된 요청은 요금이 부과되지 않습니다. 충전 금액과 보너스에 대해서는 가격 책정 페이지를 참조하세요. $0.50의 무료 체험 크레딧은 해당 크기의 약 900개의 요청을 커버합니다 (0.50 / 0.00055).
더 많은 가이드
질문과 답변
OpenAI 호환 엔드포인트의 기본 URL은 무엇인가요?
base URL로 https://api.openrouteralternativeapi.com/v1을 사용하고 키를 Bearer 토큰으로 전송하세요. 모델 ID는 uncensored입니다.
사용 가능한 라우트는 무엇인가요?
생성에는 POST /v1/chat/completions, 모델 목록에는 GET /v1/models을 사용하세요. 임베딩, 이미지, 오디오 또는 파인튜닝 라우트는 없습니다.
URL과 키 외에 코드를 변경해야 하나요?
보통 모델 문자열만 변경합니다. 요청 본문에서 공급업체 선호도 또는 폴백 목록과 같은 라우터 전용 필드를 제거하세요.
HTTP 429 오류가 발생하는 이유는 무엇입니까?
오류 코드를 확인하세요. 속도 제한은 분당 요청 수가 너무 많음을 의미하고, concurrency는 동시에 너무 많은 요청이 있음을 의미하며, Retry-After: 5 헤더는 일시적인 과부하를 의미합니다.