메인 콘텐츠로 건너뛰기
이 가이드는 애플리케이션을 YouRouter에 연결하고, 첫 요청을 보낸 뒤 응답 구조가 기대와 맞는지 확인하는 방법을 설명합니다. YouRouter는 https://api.yourouter.ai/v1에서 OpenAI 호환 엔드포인트를 제공하므로, 기존 OpenAI SDK 연동은 대개 base_url과 API 키만 바꾸면 됩니다.
API 키가 필요하면 YouRouter Dashboard에서 생성하세요.

연동 기본 정보

항목
Base URLhttps://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"
API 키를 브라우저 코드, 모바일 앱, 공개 저장소 또는 클라이언트 로그에 노출하지 마세요.

2. 첫 테스트 요청

가장 빠른 연동 검증은 Chat Completions 엔드포인트로 직접 HTTP 요청을 보내는 것입니다. 성공 시 모델 출력은 choices[0].message.content에서 읽을 수 있습니다. cURL 또는 표준 HTTP 클라이언트를 사용할 수 있으며, 아래 예시는 Python, Node.js, Go, Java, 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"
      }
    ]
  }'

3. 기존 OpenAI SDK 코드 이전

이미 OpenAI SDK를 쓰는 앱이라면 요청 본문 구조는 유지하고 api_keybase_url 두 필드만 바꾸는 경우가 많습니다.
pip install openai
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)
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 Dashboard에 표시되는 사용 가능한 모델 ID로 바꾸세요.
기본적으로 YouRouter는 자동 라우팅합니다. vendor 헤더를 생략하거나 vendor: auto로 두면 현재 가장 적합한 사용 가능한 상위 제공업체로 라우팅합니다. 연동이 특정 상위 제공업체의 동작, 모델 변형, 계정 격리 또는 규정 준수에 명확히 의존할 때만 vendor로 고정하세요.
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."}]
  }'
모델 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, 도구 호출, 멀티모달 흐름을 구축합니다.