> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API 레퍼런스

> TokenLab API에 대한 전체 레퍼런스

## 개요

TokenLab는 **네이티브 우선이며 OpenAI 호환입니다**. 네이티브 동작이 필요할 때는 Anthropic에는 `POST /v1/messages`, Gemini에는 `/v1beta/models/...:generateContent`와 같은 공급자 네이티브 경로를 사용하고, 기존 OpenAI 스타일 SDK나 도구를 마이그레이션할 때는 OpenAI 호환 `/v1` 엔드포인트를 사용하세요. `POST /v1/responses`는 Responses 전용 동작을 위한 고급 선택 경로로 남아 있습니다.

## 베이스 URL

```
https://api.tokenlab.sh
```

## 인증

모든 API 엔드포인트는 Bearer 토큰을 사용한 인증이 필요합니다:

```bash theme={null}
Authorization: Bearer sk-your-api-key
```

[대시보드](https://tokenlab.sh/dashboard)에서 API 키를 확인하세요.

<Warning>
  **인터랙티브 플레이그라운드 안내**: 이 문서 사이트의 플레이그라운드는 데모 전용이며 API 키 입력을 지원하지 않습니다. API를 테스트하려면 다음을 사용하세요:

  * **cURL** - 예시 명령어를 복사하고 `sk-your-api-key`를 실제 키로 교체하세요.
  * **Postman** - 당사의 [OpenAPI 사양](/openapi.json)을 가져오기 하세요.
  * **SDK** - 당사의 베이스 URL과 함께 OpenAI/Anthropic SDK를 사용하세요.
</Warning>

## 지원되는 엔드포인트

### 채팅 및 텍스트 생성

| 엔드포인트                  | 메서드  | 설명                   |
| ---------------------- | ---- | -------------------- |
| `/v1/chat/completions` | POST | OpenAI 호환 채팅 완성      |
| `/v1/messages`         | POST | Anthropic 호환 메시지 API |
| `/v1/responses`        | POST | OpenAI Responses API |

### 임베딩 및 리랭크 (Rerank)

| 엔드포인트            | 메서드  | 설명         |
| ---------------- | ---- | ---------- |
| `/v1/embeddings` | POST | 텍스트 임베딩 생성 |
| `/v1/rerank`     | POST | 문서 리랭크     |

### 이미지

| 엔드포인트                         | 메서드  | 설명                              |
| ----------------------------- | ---- | ------------------------------- |
| `/v1/images/generations`      | POST | 텍스트로 이미지 생성                     |
| `/v1/images/edits`            | POST | 이미지 편집                          |
| `/v1/images/generations/{id}` | GET  | 태스크 기반 이미지 응답을 위한 이미지 태스크 상태 경로 |

<Info>
  일부 이미지 모델은 결과를 인라인으로 반환하고, 일부는 태스크 기반 응답을 반환하며, 일부는 라우팅된 프로바이더 경로에 따라 두 방식 중 하나로 동작할 수 있습니다. 생성 응답에 `poll_url`이 포함되어 있다면 해당 URL을 그대로 따르세요.
</Info>

### 오디오

| 엔드포인트                      | 메서드  | 설명              |
| -------------------------- | ---- | --------------- |
| `/v1/audio/speech`         | POST | 텍스트 음성 변환 (TTS) |
| `/v1/audio/transcriptions` | POST | 음성 텍스트 변환 (STT) |

### 실시간

| 엔드포인트                        | 메서드 | 설명               |
| ---------------------------- | --- | ---------------- |
| `/v1/realtime?model={model}` | WS  | 실시간 WebSocket 세션 |

<Info>
  `/v1/realtime`은 WebSocket 업그레이드 요청에 사용합니다. 일반 `GET /v1/realtime`은 WebSocket 라우트를 직접 확인할 수 없는 클라이언트를 위해 엔드포인트 메타데이터를 반환합니다. 이는 OpenAI Realtime REST 표면이 아닙니다. client secret, translation client secret, Calls, legacy beta session 엔드포인트는 현재 제공하지 않습니다.
</Info>

### 비디오

| 엔드포인트                         | 메서드  | 설명                       |
| ----------------------------- | ---- | ------------------------ |
| `/v1/videos/generations`      | POST | 비디오 생성 태스크 생성            |
| `/v1/tasks/{id}`              | GET  | 비디오 작업에 대한 비동기 태스크 상태 조회 |
| `/v1/videos/generations/{id}` | GET  | 레거시 호환 비디오 태스크 상태 경로     |

<Info>
  신규 클라이언트의 경우 `/v1/tasks/{id}`를 권장하며 생성 응답에서 반환된 `poll_url`을 따르세요. `/v1/videos/generations/{id}`는 하위 호환성을 위해서만 유지됩니다.
</Info>

### 비동기 태스크

| 엔드포인트            | 메서드 | 설명                                               |
| ---------------- | --- | ------------------------------------------------ |
| `/v1/tasks/{id}` | GET | 통합 비동기 태스크 상태 엔드포인트. 반환된 `poll_url`을 따를 때 권장됩니다. |

<Info>
  이 엔드포인트는 비디오, 음악, 3D에 국한되지 않습니다. 일부 이미지 태스크도 `/v1/tasks/{id}`를 표준 폴링 경로로 사용할 수 있습니다.
</Info>

### 음악

| 엔드포인트                        | 메서드  | 설명           |
| ---------------------------- | ---- | ------------ |
| `/v1/music/generations`      | POST | 음악 생성 태스크 생성 |
| `/v1/music/generations/{id}` | GET  | 음악 전용 상태 경로  |

<Info>
  신규 클라이언트의 경우 반환된 `poll_url`을 우선적으로 사용하세요. 고정된 태스크 상태 엔드포인트가 필요한 경우 `/v1/tasks/{id}`를 사용하고, `/v1/music/generations/{id}`는 음악 전용 호환성 경로로 유지하세요.
</Info>

### 3D 생성

| 엔드포인트                     | 메서드  | 설명              |
| ------------------------- | ---- | --------------- |
| `/v1/3d/generations`      | POST | 3D 모델 생성 태스크 생성 |
| `/v1/3d/generations/{id}` | GET  | 3D 전용 상태 경로     |

<Info>
  신규 클라이언트의 경우 반환된 `poll_url`을 우선적으로 사용하세요. 고정된 태스크 상태 엔드포인트가 필요한 경우 `/v1/tasks/{id}`를 사용하고, `/v1/3d/generations/{id}`는 3D 전용 호환성 경로로 유지하세요.
</Info>

### 모델

| 엔드포인트                | 메서드 | 설명                 |
| -------------------- | --- | ------------------ |
| `/v1/models`         | GET | 사용 가능한 모든 모델 목록 조회 |
| `/v1/models/{model}` | GET | 특정 모델 정보 조회        |

### Gemini (v1beta)

네이티브 Google Gemini API 형식 지원:

| 엔드포인트                                          | 메서드  | 설명                     |
| ---------------------------------------------- | ---- | ---------------------- |
| `/v1beta/models/{model}:generateContent`       | POST | 콘텐츠 생성 (Gemini 형식)     |
| `/v1beta/models/{model}:streamGenerateContent` | POST | 스트림 콘텐츠 생성 (Gemini 형식) |

<Note>
  Gemini 엔드포인트는 표준 Bearer 토큰 외에 `?key=` 쿼리 파라미터 인증을 지원합니다.
</Note>

## 응답 형식

모든 응답은 일관된 형식을 따릅니다:

### 성공 응답

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4o",
  "choices": [...],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```

### 라우팅 투명성

모든 응답에는 채널 정보가 포함된 `_routing` 필드가 포함됩니다:

```json theme={null}
{
  "id": "chatcmpl-abc123",
  ...,
  "_routing": {
    "channel": {
      "id": "ch_xxx",
      "name": "channel-name",
      "provider": "openai",
      "channelType": "PLATFORM"
    },
    "cached": false,
    "retryCount": 0
  }
}
```

| 필드                    | 설명                                        |
| --------------------- | ----------------------------------------- |
| `channel.id`          | 사용된 채널 식별자                                |
| `channel.provider`    | 업스트림 프로바이더 (openai, anthropic 등)          |
| `channel.channelType` | `PLATFORM` (TokenLab) 또는 `PRIVATE` (BYOK) |
| `cached`              | 응답이 캐시에서 제공되었는지 여부                        |
| `retryCount`          | 재시도 횟수 (있는 경우)                            |

### 오류 응답

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}
```

## 속도 제한 (Rate Limits)

속도 제한은 역할 기반이며 관리자가 설정할 수 있습니다. 기본값은 다음과 같습니다:

| 역할      | 분당 요청 수 (Requests/min) |
| ------- | ---------------------- |
| User    | 1,000                  |
| Partner | 10,000                 |
| VIP     | 10,000                 |

<Note>
  맞춤형 속도 제한은 고객 지원에 문의하세요. 정확한 값은 계정 설정에 따라 다를 수 있습니다.
</Note>

속도 제한을 초과하면 API는 `429` 상태 코드와 함께 대기 시간을 나타내는 `Retry-After` 헤더를 반환합니다.

## OpenAPI 사양

<Card title="OpenAPI 사양" icon="file-code" href="/openapi.json">
  전체 OpenAPI 3.0 사양 다운로드
</Card>