이 가이드는 애플리케이션을 YouRouter에 연결하고, 첫 요청을 보낸 뒤 응답 구조가 기대와 맞는지 확인하는 방법을 설명합니다. YouRouter는 https://api.yourouter.ai/v1에서 OpenAI 호환 엔드포인트를 제공하므로, 기존 OpenAI SDK 연동은 대개 base_url과 API 킀만 바꾸면 됩니다.
연동 기본 정보 항목 값 Base URL https://api.yourouter.ai/v1인증 헤더 Authorization: Bearer <YOUR_YOUROUTER_API_KEY>콘텐츠 타입 Content-Type: application/json모델 필드 model에 대상 모델 ID 지정멀티모달 입력 messages[].content에 텍스트와 이미지 블록 전달기본 라우팅 vendor 생략 또는 vendor: auto제공업체 고정 vendor: openai, vendor: anthropic, vendor: google 등
1. API 키 설정 아래 예제를 실행하기 전에 API 키를 환경 변수에 넣으세요.
export YOUROUTER_API_KEY = "your-api-key-here"
set YOUROUTER_API_KEY = your - api - key - here
YOUROUTER_API_KEY = your-api-key-here
API 키를 브라우저 코드, 모바일 앱, 공개 저장소 또는 클라이언트 로그에 노출하지 마세요.
2. 첫 테스트 요청 가장 빠른 연동 검증은 Chat Completions 엔드포인트로 직접 HTTP 요청을 보내는 것입니다. 성공 시 모델 출력은 choices[0].message.content에서 읽을 수 있습니다.
cURL
Python requests
Node.js fetch
curl https://api.yourouter.ai/v1/chat/completions \ -H "Authorization: Bearer $YOUROUTER_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [ { "role": "user", "content": "Reply with exactly: connected" } ] }'
import os import requests response = requests.post( "https://api.yourouter.ai/v1/chat/completions" , headers = { "Authorization" : f "Bearer { os.environ[ 'YOUROUTER_API_KEY' ] } " , "Content-Type" : "application/json" , }, json = { "model" : "gpt-4o" , "messages" : [ { "role" : "user" , "content" : "Reply with exactly: connected" , } ], }, ) print (response.json()[ "choices" ][ 0 ][ "message" ][ "content" ])
const response = await fetch ( 'https://api.yourouter.ai/v1/chat/completions' , { method: 'POST' , headers: { Authorization: `Bearer ${ process . env . YOUROUTER_API_KEY } ` , 'Content-Type' : 'application/json' , }, body: JSON . stringify ({ model: 'gpt-4o' , messages: [ { role: 'user' , content: 'Reply with exactly: connected' , }, ], }), }); const data = await response . json (); console . log ( data . choices [ 0 ]. message . content );
3. 기존 OpenAI SDK 코드 이전 이미 OpenAI SDK를 쓰는 앱이라면 요청 본문 구조는 유지하고 api_key와 base_url 두 필드만 바꾸는 경우가 많습니다.
import os from openai import OpenAI client = OpenAI( api_key = os.environ[ "YOUROUTER_API_KEY" ], base_url = "https://api.yourouter.ai/v1" , ) completion = client.chat.completions.create( model = "gpt-4o" , messages = [ { "role" : "user" , "content" : "Reply with exactly: connected" , } ], ) print (completion.choices[ 0 ].message.content)
import OpenAI from 'openai' ; const openai = new OpenAI ({ apiKey: process . env . YOUROUTER_API_KEY , baseURL: 'https://api.yourouter.ai/v1' , }); const completion = await openai . chat . completions . create ({ model: 'gpt-4o' , messages: [ { role: 'user' , content: 'Reply with exactly: connected' , }, ], }); console . log ( completion . choices [ 0 ]. message . content );
4. 모델과 라우팅 선택 model 필드로 모델을 고릅니다. OpenAI GPT, Claude, Gemini, DeepSeek, Grok, Doubao, Kimi 등 여러 패밀리를 같은 API 형태로 호출할 수 있습니다. 이미지 등 멀티모달 입력은 멀티모달 가이드 를 참고하세요.기본적으로 YouRouter는 자동 라우팅합니다. vendor 헤더를 생략하거나 vendor: auto로 두면 현재 가장 적합한 사용 가능한 상위로 라우팅합니다.
연동이 특정 상위의 동작, 모델 변형, 계정 격리 또는 규정 준수에 명확히 의존할 때만 vendor로 고정하세요.
cURL
Python SDK
Node.js SDK
curl https://api.yourouter.ai/v1/chat/completions \ -H "Authorization: Bearer $YOUROUTER_API_KEY " \ -H "Content-Type: application/json" \ -H "vendor: openai" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "Hello from a pinned provider."}] }'
completion = client.chat.completions.create( model = "gpt-4o" , messages = [{ "role" : "user" , "content" : "Hello from a pinned provider." }], extra_headers = { "vendor" : "openai" }, )
const completion = await openai . chat . completions . create ({ model: 'gpt-4o' , messages: [{ role: 'user' , content: 'Hello from a pinned provider.' }], }, { headers: { vendor: 'openai' }, });
모델과 상위에 대한 추가 설명은 모델 과 라우팅 가이드 를 참고하세요.
5. 응답과 오류 처리 OpenAI 호환 인터페이스의 성공 응답은 OpenAI 스타일 형식을 따릅니다. 생성 텍스트는 보통 choices[0].message.content에 있습니다.
{ "choices" : [ { "message" : { "role" : "assistant" , "content" : "connected" } } ] }
자주 보는 상태 코드:
코드 의미 권장 조치 200성공 응답 본문 파싱 401API 키 누락 또는 무효 Authorization 헤더 확인429상위 속도 제한 백오프 후 재시도 또는 라우팅 조정 500게이트웨이 또는 상위 오류 안전하게 재시도하고 요청 ID 기록
6. 스트리밍 채팅 UI나 에이전트에서는 stream: true로 설정해 모델이 생성하는 동안 조각 단위로 응답을 받을 수 있습니다.
stream = client.chat.completions.create( model = "gpt-4o" , messages = [{ "role" : "user" , "content" : "Explain automatic routing in two sentences." }], stream = True , ) for chunk in stream: delta = chunk.choices[ 0 ].delta.content if delta: print (delta, end = "" )
전체 요청 형식은 Create Chat Completion 을 참고하세요.
다음 단계
모델 모델 ID, 패밀리, vendor 사용법을 확인합니다.
API 레퍼런스 엔드포인트, 매개변수, 응답 형식을 확인합니다.
멀티모달 이미지 입력과 네이티브 멀티모달 기능을 확인합니다.
라우팅 가이드 자동 라우팅과 제공업체 고정의 적용 시점을 이해합니다.
