이 가이드는 애플리케이션을 YouRouter에 연결하고, 첫 요청을 보낸 뒤 응답 구조가 기대와 맞는지 확인하는 방법을 설명합니다. YouRouter는 https://api.yourouter.ai/v1에서 OpenAI 호환 엔드포인트를 제공하므로, 기존 OpenAI SDK 연동은 대개 base_url과 API 키만 바꾸면 됩니다.
연동 기본 정보
항목 값 Base URL https://api.yourouter.ai/v1인증 헤더 Authorization: Bearer <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 또는 표준 HTTP 클라이언트를 사용할 수 있으며, 아래 예시는 Python, Node.js, Go, Java, PHP, Rust를 포함합니다.
cURL
Python requests
Node.js 18+ fetch
Go
Java 11+
PHP
Rust
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" ,
}
],
},
)
response.raise_for_status()
print (response.json()[ "choices" ][ 0 ][ "message" ][ "content" ])
// quickstart.mjs로 저장하고 Node.js 18+에서 실행합니다.
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' ,
},
],
}),
});
if ( ! response . ok ) {
throw new Error ( await response . text ());
}
const data = await response . json ();
console . log ( data . choices [ 0 ]. message . content );
package main
import (
" bytes "
" encoding/json "
" fmt "
" io "
" net/http "
" os "
)
func main () {
payload , _ := json . Marshal ( map [ string ] any {
"model" : "gpt-4o" ,
"messages" : [] map [ string ] string {
{ "role" : "user" , "content" : "Reply with exactly: connected" },
},
})
req , err := http . NewRequest (
"POST" ,
"https://api.yourouter.ai/v1/chat/completions" ,
bytes . NewReader ( payload ),
)
if err != nil {
panic ( err )
}
req . Header . Set ( "Authorization" , "Bearer " + os . Getenv ( "YOUROUTER_API_KEY" ))
req . Header . Set ( "Content-Type" , "application/json" )
res , err := http . DefaultClient . Do ( req )
if err != nil {
panic ( err )
}
defer res . Body . Close ()
if res . StatusCode >= 400 {
body , _ := io . ReadAll ( res . Body )
panic ( fmt . Sprintf ( "request failed: %s \n %s " , res . Status , body ))
}
var result struct {
Choices [] struct {
Message struct {
Content string `json:"content"`
} `json:"message"`
} `json:"choices"`
}
if err := json . NewDecoder ( res . Body ). Decode ( & result ); err != nil {
panic ( err )
}
fmt . Println ( result . Choices [ 0 ]. Message . Content )
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Quickstart {
public static void main ( String [] args ) throws Exception {
String body = String . join ( " \n " ,
"{" ,
" \" model \" : \" gpt-4o \" ," ,
" \" messages \" : [" ,
" {" ,
" \" role \" : \" user \" ," ,
" \" content \" : \" Reply with exactly: connected \" " ,
" }" ,
" ]" ,
"}"
);
HttpRequest request = HttpRequest . newBuilder ()
. uri ( URI . create ( "https://api.yourouter.ai/v1/chat/completions" ))
. header ( "Authorization" , "Bearer " + System . getenv ( "YOUROUTER_API_KEY" ))
. header ( "Content-Type" , "application/json" )
. POST ( HttpRequest . BodyPublishers . ofString (body))
. build ();
HttpResponse < String > response = HttpClient . newHttpClient (). send (
request,
HttpResponse . BodyHandlers . ofString ()
);
if ( response . statusCode () >= 400 ) {
throw new RuntimeException ( response . body ());
}
System . out . println ( response . body ());
}
}
<? php
$apiKey = getenv ( 'YOUROUTER_API_KEY' );
$payload = json_encode ([
'model' => 'gpt-4o' ,
'messages' => [
[
'role' => 'user' ,
'content' => 'Reply with exactly: connected' ,
],
],
]);
$ch = curl_init ( 'https://api.yourouter.ai/v1/chat/completions' );
curl_setopt_array ( $ch , [
CURLOPT_RETURNTRANSFER => true ,
CURLOPT_POST => true ,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey ,
'Content-Type: application/json' ,
],
CURLOPT_POSTFIELDS => $payload ,
]);
$response = curl_exec ( $ch );
$status = curl_getinfo ( $ch , CURLINFO_HTTP_CODE );
if ( $response === false ) {
throw new RuntimeException ( curl_error ( $ch ));
}
curl_close ( $ch );
if ( $status >= 400 ) {
throw new RuntimeException ( $response );
}
$data = json_decode ( $response , true );
echo $data [ 'choices' ][ 0 ][ 'message' ][ 'content' ] . PHP_EOL ;
cargo add reqwest --features blocking,json
cargo add serde_json
use reqwest :: blocking :: Client ;
use serde_json :: json;
use std :: env;
fn main () -> Result <(), Box < dyn std :: error :: Error >> {
let api_key = env :: var ( "YOUROUTER_API_KEY" ) ? ;
let response : serde_json :: Value = Client :: new ()
. post ( "https://api.yourouter.ai/v1/chat/completions" )
. bearer_auth ( api_key )
. json ( & json! ({
"model" : "gpt-4o" ,
"messages" : [
{
"role" : "user" ,
"content" : "Reply with exactly: connected"
}
]
}))
. send () ?
. error_for_status () ?
. json () ? ;
if let Some ( content ) = response [ "choices" ][ 0 ][ "message" ][ "content" ] . as_str () {
println! ( "{content}" );
}
Ok (())
}
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 );
Go, Java, PHP, Rust도 같은 사용자 지정 Base URL 방식을 사용합니다. 사용하는 OpenAI 호환 SDK가 base URL 설정을 지원하면 https://api.yourouter.ai/v1을 지정하고, 지원하지 않으면 위의 HTTP 예시로 /v1/chat/completions를 직접 호출하세요.
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' },
});
모델 API 예시는 모델 을, 제공업체 ID, 자동 장애 조치 동작, 프로덕션 권장 사항은 라우팅 가이드 를 참고하세요.
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 을 참고하세요.
다음 단계
API 레퍼런스 엔드포인트, 매개변수, 응답 형식을 확인합니다.
모델 모델 ID를 전달하고 API로 모델을 전환하는 방법을 확인합니다.
멀티모달 이미지 입력을 보내고 제공업체 네이티브 멀티모달 API를 호출합니다.
라우팅 가이드 자동 라우팅과 제공업체 고정의 적용 시점을 이해합니다.
Chat Completions 대화, 스트리밍 UI, 도구 호출, 멀티모달 흐름을 구축합니다.