> For the complete documentation index, see [llms.txt](https://runyourai.gitbook.io/userguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://runyourai.gitbook.io/userguide/api/guide/link.md).

# API 연동하기

RunYour AI API를 서비스에 연동하는 방법을 안내합니다. OpenAI SDK를 사용하는 방법과 REST API를 직접 호출하는 방법, 두 가지 중 편한 방식을 선택하세요.

***

### OpenAI SDK로 연동하기 (권장)

기존에 OpenAI SDK를 사용 중이라면 **Base URL과 API 키 두 가지만 변경**하면 됩니다.

#### 1단계. SDK 설치하기

{% tabs %}
{% tab title="Python" %}

```bash
pip install openai
```

{% endtab %}

{% tab title="JavaScript" %}

```bash
npm install openai
```

{% endtab %}
{% endtabs %}

#### 2단계. 클라이언트 설정하기

{% tabs %}
{% tab title="Python" %}

```python
from openai import OpenAI

client = OpenAI(
    api_key="runyour-v1-YOUR_API_KEY",   # ← RunYour AI API 키
    base_url="https://api.runyour.ai/v1"  # ← Base URL 변경
)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.RUNYOUR_API_KEY,       // ← 환경 변수로 관리
  baseURL: "https://api.runyour.ai/v1",      // ← Base URL 변경
});
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
기존 OpenAI 코드에서 `api_key`와 `base_url`(또는 `baseURL`) 두 줄만 교체하면 됩니다. 나머지 코드는 그대로 사용할 수 있습니다.
{% endhint %}

#### 3단계. 첫 번째 API 호출 테스트하기

{% tabs %}
{% tab title="Python" %}

```python
completion = client.chat.completions.create(
    model="openai/gpt-5.2",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "안녕하세요!"}
    ],
    temperature=0.7,
    max_tokens=300
)

print(completion.choices[0].message.content)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const completion = await client.chat.completions.create({
  model: "openai/gpt-5.2",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "안녕하세요!" }
  ],
  temperature: 0.7,
  max_tokens: 300,
});

console.log(completion.choices[0]?.message?.content);
```

{% endtab %}
{% endtabs %}

응답에서 AI의 답변은 `choices[0].message.content`에서 확인할 수 있습니다.

***

### REST API로 직접 연동하기

SDK 없이 `curl`, Postman, 또는 자체 HTTP 클라이언트로 직접 호출할 수도 있습니다.

#### 기본 호출 예시

```bash
curl https://api.runyour.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer runyour-v1-YOUR_API_KEY" \
  -d '{
    "model": "openai/gpt-5.2",
    "messages": [
      { "role": "user", "content": "안녕하세요!" }
    ],
    "temperature": 0.7,
    "max_tokens": 300
  }'
```

#### 주요 엔드포인트

<table><thead><tr><th width="124.140625">메서드</th><th>엔드포인트</th><th>설명</th></tr></thead><tbody><tr><td><code>POST</code></td><td><code>https://api.runyour.ai/v1/chat/completions</code></td><td>AI 응답 생성 (주요 엔드포인트)</td></tr><tr><td><code>POST</code></td><td><code>https://api.runyour.ai/v1/responses</code></td><td>OpenAI Responses API 형식 호출</td></tr><tr><td><code>GET</code></td><td><code>https://api.runyour.ai/v1/models</code></td><td>사용 가능한 모델 목록 조회</td></tr></tbody></table>

#### 요청 시 사용할 수 있는 주요 파라미터

{% tabs %}
{% tab title="Chat Completions API" %}

<table><thead><tr><th width="159.578125">파라미터</th><th width="79.96875">필수</th><th>설명</th></tr></thead><tbody><tr><td><code>model</code></td><td>✅</td><td>호출할 모델 ID. <code>provider/model</code> 형식 (예: <code>openai/gpt-5.2</code>)</td></tr><tr><td><code>messages</code></td><td>✅</td><td>대화 메시지 배열. <code>role</code>(<code>system</code>·<code>user</code>·<code>assistant</code>)과 <code>content</code>로 구성</td></tr><tr><td><code>temperature</code></td><td></td><td>응답의 창의성 조절. <code>0</code>(결정적) ~ <code>2</code>(창의적), 기본값 <code>1.0</code></td></tr><tr><td><code>max_tokens</code></td><td></td><td>생성할 최대 토큰 수. 미설정 시 모델 기본값 적용</td></tr><tr><td><code>stream</code></td><td></td><td><code>true</code>로 설정하면 스트리밍 응답 활성화. 기본값 <code>false</code></td></tr><tr><td><code>response_format</code></td><td></td><td>응답 형식 지정. <code>{ "type": "text" }</code> 또는 <code>{ "type": "json_object" }</code></td></tr><tr><td><code>enable_web_search</code></td><td></td><td><code>true</code>로 설정하면 실시간 웹 검색 결과를 반영한 답변 생성 (지원 모델에 한함)</td></tr><tr><td><code>reasoning_config</code></td><td></td><td>OpenAI 추론 모델 전용. <code>effort</code>(<code>none</code>·<code>low</code>·<code>medium</code>·<code>high</code>·<code>xhigh</code>), <code>summary</code>(<code>auto</code>·<code>none</code>·<code>concise</code>·<code>detailed</code>)</td></tr></tbody></table>
{% endtab %}

{% tab title="Responses API" %}

<table><thead><tr><th width="160.38671875">파라미터</th><th width="79.640625">필수</th><th>설명</th></tr></thead><tbody><tr><td><code>model</code></td><td>✅</td><td>호출할 모델 ID. <code>provider/model</code> 형식 (예: <code>openai/gpt-5</code>)</td></tr><tr><td><code>input</code></td><td>✅</td><td>사용자 입력. 문자열 또는 메시지 배열(<code>role</code> + <code>content</code>)로 구성</td></tr><tr><td><code>instructions</code></td><td></td><td>시스템 레벨 지시사항. Chat Completions의 <code>system</code> 메시지에 해당</td></tr><tr><td><code>max_output_tokens</code></td><td></td><td>생성할 최대 토큰 수. 미설정 시 모델 기본값 적용</td></tr><tr><td><code>temperature</code></td><td></td><td>응답의 창의성 조절. <code>0</code>(결정적) ~ <code>2</code>(창의적)</td></tr><tr><td><code>stream</code></td><td></td><td><code>true</code>로 설정하면 스트리밍 응답 활성화. <strong>OpenAI 모델에서만 지원</strong></td></tr><tr><td><code>reasoning</code></td><td></td><td>추론 모델 전용. <code>{ "effort": "low" | "medium" | "high" }</code></td></tr><tr><td><code>response_format</code></td><td></td><td>응답 형식 지정. <code>json_object</code> 또는 <code>json_schema</code></td></tr><tr><td><code>tools</code></td><td></td><td>함수 도구 정의 배열</td></tr><tr><td><code>tool_choice</code></td><td></td><td>도구 선택 전략. <code>none</code>·<code>auto</code>·<code>required</code> 또는 특정 함수 지정</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

#### 응답 예시

```json
{
  "id": "chatcmpl-2f3e0c18-...",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "openai/gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 무엇을 도와드릴까요?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 18,
    "total_tokens": 30
  }
}
```

AI의 답변은 `choices[0].message.content`에서 확인할 수 있으며, `usage`에서 이번 호출에 사용된 토큰 수를 확인할 수 있습니다.