> ## 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 개요

> 모델 API 호출의 Base URL, 인증, 요청 헤더 및 응답 규약입니다.

YouRouter는 단일 게이트웨이를 통해 모델 API를 노출합니다. 대부분의 연동은 OpenAI 호환 Chat Completions 엔드포인트부터 시작하는 것이 좋습니다.

## Base URL

```text theme={null}
https://api.yourouter.ai/v1
```

OpenAI 호환 API와 제공업체 네이티브 모델 API는 이 base URL을 사용합니다. 영상 작업과 Custom Search는 별도의 base path를 사용합니다.

## 엔드포인트 패밀리

| 패밀리           | Base path                                  | 용도                                                                             |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
| 모델 API        | `https://api.yourouter.ai/v1`              | Chat Completions, Embeddings, Anthropic Messages, Google `generateContent` 경로. |
| 영상 작업         | `https://api.yourouter.ai/api/v3`          | Ark 텍스트-영상 및 이미지-영상 작업 생성과 폴링.                                                 |
| Custom Search | `https://api.yourouter.ai/customsearch/v1` | Google Programmable Search 호환 웹 검색.                                            |

## 인증

YouRouter API 키를 Bearer 토큰으로 전송하세요.

```bash theme={null}
Authorization: Bearer <YOUROUTER_API_KEY>
```

JSON 요청의 경우 다음도 함께 보냅니다.

```bash theme={null}
Content-Type: application/json
```

<Warning>
  API 키는 서버 측 코드, 백엔드 서비스, CI 작업 또는 신뢰할 수 있는 내부 도구에서만 사용하세요. 브라우저 코드나 모바일 클라이언트에 넣지 마세요.
</Warning>

## 첫 API 요청

```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"
      }
    ]
  }'
```

생성된 텍스트는 보통 다음 위치에 있습니다.

```text theme={null}
choices[0].message.content
```

## 핵심 개념

| 개념            | 사용 방법                                                                 |
| ------------- | --------------------------------------------------------------------- |
| 모델 선택         | 요청 본문의 `model` 필드를 설정합니다.                                             |
| 멀티모달 입력       | `messages[].content`에 텍스트와 이미지 블록을 보내거나, 제공업체 네이티브 멀티모달 엔드포인트를 사용합니다. |
| 자동 라우팅        | `vendor` 헤더를 생략하거나 `vendor: auto`를 보냅니다.                              |
| 제공업체 고정       | `vendor: openai`, `vendor: anthropic`, `vendor: google` 등의 값을 보냅니다.   |
| 스트리밍          | `stream: true`로 설정하면 SSE로 내용이 증분 반환됩니다.                               |
| 제공업체 네이티브 API | Anthropic은 `/messages`, Gemini는 `generateContent` 경로를 사용합니다.          |

## 주요 엔드포인트

| 엔드포인트                                               | 용도                                         |
| --------------------------------------------------- | ------------------------------------------ |
| `POST /chat/completions`                            | OpenAI 호환 텍스트 및 이미지 입력 호출. 대부분의 연동에 적합합니다. |
| `POST /embeddings`                                  | 텍스트 임베딩 생성.                                |
| `POST /messages`                                    | Anthropic Messages 호환 호출.                  |
| `POST /projects/.../models/{model}:generateContent` | Google Gemini `generateContent` 호환 호출.     |
| `POST /api/v3/contents/generations/tasks`           | 작업 기반 영상 생성 호출.                            |

## 상태 코드

| 상태 코드 | 의미                          |
| ----- | --------------------------- |
| `200` | 요청 성공.                      |
| `400` | 요청 본문, 모델 또는 매개변수 형식이 잘못됨.  |
| `401` | API 키가 없거나 잘못됨.             |
| `429` | 제공업체의 속도 제한 또는 동시성 제한에 도달함. |
| `500` | 게이트웨이 또는 상위 제공업체 내부 오류.     |

핵심 요청 형식은 [Create Chat Completion](/ko/api-reference/chat/create)을, 이미지 및 영상 예시는 [멀티모달](/ko/guides/multimodal)을 참고하세요.