> ## Documentation Index > Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt > Use this file to discover all available pages before exploring further. # API 빠른 시작 > 몇 분 안에 YouRouter API에 앱을 연결합니다. 이 가이드는 애플리케이션을 YouRouter에 연결하고, 첫 요청을 보낸 뒤 응답 구조가 기대와 맞는지 확인하는 방법을 설명합니다. YouRouter는 `https://api.yourouter.ai/v1`에서 OpenAI 호환 엔드포인트를 제공하므로, 기존 OpenAI SDK 연동은 대개 `base_url`과 API 키만 바꾸면 됩니다. API 키가 필요하면 [YouRouter Dashboard](https://platform.yourouter.ai/dashboard)에서 생성하세요. ## 연동 기본 정보 | 항목 | 값 | | -------- | --------------------------------------------------------- | | Base URL | `https://api.yourouter.ai/v1` | | 인증 헤더 | `Authorization: Bearer ` | | 콘텐츠 타입 | `Content-Type: application/json` | | 모델 필드 | `model`에 대상 모델 ID 지정 | | 멀티모달 입력 | `messages[].content`에 텍스트와 이미지 블록 전달 | | 기본 라우팅 | `vendor` 생략 또는 `vendor: auto` | | 제공업체 고정 | `vendor: openai`, `vendor: anthropic`, `vendor: google` 등 | ## 1. API 키 설정 아래 예제를 실행하기 전에 API 키를 환경 변수에 넣으세요. ```bash theme={null} export YOUROUTER_API_KEY="your-api-key-here" ``` ```cmd theme={null} set YOUROUTER_API_KEY=your-api-key-here ``` ```bash theme={null} 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를 포함합니다. ```bash theme={null} 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" } ] }' ``` ```bash theme={null} pip install requests ``` ```python theme={null} 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"]) ``` ```javascript theme={null} // 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); ``` ```go theme={null} 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) } ``` ```java theme={null} 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 response = HttpClient.newHttpClient().send( request, HttpResponse.BodyHandlers.ofString() ); if (response.statusCode() >= 400) { throw new RuntimeException(response.body()); } System.out.println(response.body()); } } ``` ```php theme={null} '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; ``` ```bash theme={null} cargo add reqwest --features blocking,json cargo add serde_json ``` ```rust theme={null} use reqwest::blocking::Client; use serde_json::json; use std::env; fn main() -> Result<(), Box> { 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` 두 필드만 바꾸는 경우가 많습니다. ```bash theme={null} pip install openai ``` ```python theme={null} 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) ``` ```bash theme={null} npm install openai ``` ```javascript theme={null} 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 형태로 호출할 수 있습니다. 이미지 등 멀티모달 입력은 [멀티모달 가이드](/ko/guides/multimodal)를 참고하세요. 예시 모델이 계정에서 활성화되어 있지 않다면 [YouRouter Dashboard](https://platform.yourouter.ai/dashboard)에 표시되는 사용 가능한 모델 ID로 바꾸세요. 기본적으로 YouRouter는 자동 라우팅합니다. `vendor` 헤더를 생략하거나 `vendor: auto`로 두면 현재 가장 적합한 사용 가능한 상위 제공업체로 라우팅합니다. 연동이 특정 상위 제공업체의 동작, 모델 변형, 계정 격리 또는 규정 준수에 명확히 의존할 때만 `vendor`로 고정하세요. ```bash theme={null} 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."}] }' ``` ```python theme={null} completion = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Hello from a pinned provider."}], extra_headers={"vendor": "openai"}, ) ``` ```javascript theme={null} const completion = await openai.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello from a pinned provider.' }], }, { headers: { vendor: 'openai' }, }); ``` 모델 API 예시는 [모델](/ko/model)을, 제공업체 ID, 자동 장애 조치 동작, 프로덕션 권장 사항은 [라우팅 가이드](/ko/guides/router)를 참고하세요. ## 5. 응답과 오류 처리 OpenAI 호환 인터페이스의 성공 응답은 OpenAI 스타일 형식을 따릅니다. 생성 텍스트는 보통 `choices[0].message.content`에 있습니다. ```json theme={null} { "choices": [ { "message": { "role": "assistant", "content": "connected" } } ] } ``` 자주 보는 상태 코드: | 코드 | 의미 | 권장 조치 | | ----- | ------------------- | --------------------- | | `200` | 성공 | 응답 본문 파싱 | | `401` | API 키 누락 또는 무효 | `Authorization` 헤더 확인 | | `429` | 상위 제공업체 속도 제한 | 백오프 후 재시도 또는 라우팅 조정 | | `500` | 게이트웨이 또는 상위 제공업체 오류 | 안전하게 재시도하고 요청 ID 기록 | ## 6. 스트리밍 채팅 UI나 에이전트에서는 `stream: true`로 설정해 모델이 생성하는 동안 조각 단위로 응답을 받을 수 있습니다. ```python theme={null} 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](/ko/api-reference/chat/create#streaming)을 참고하세요. ## 다음 단계 엔드포인트, 매개변수, 응답 형식을 확인합니다. 모델 ID를 전달하고 API로 모델을 전환하는 방법을 확인합니다. 이미지 입력을 보내고 제공업체 네이티브 멀티모달 API를 호출합니다. 자동 라우팅과 제공업체 고정의 적용 시점을 이해합니다. 대화, 스트리밍 UI, 도구 호출, 멀티모달 흐름을 구축합니다.