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

# API 사용 가이드

> TokenHub 엔드포인트, 인증 방식, 모델 조회 API와 프로토콜 호환 정보를 정리합니다.

TokenHub는 OpenAI API 및 Anthropic API 프로토콜과 호환됩니다. OpenAI SDK를 그대로 사용해 접속할 수 있습니다.

## API 엔드포인트

리전별로 서로 다른 접속 주소를 제공합니다.

**기본 엔드포인트**

| 사이트            | API 주소                                       | 리소스 스케줄링 범위      |
| -------------- | -------------------------------------------- | ---------------- |
| Singapore      | `https://tokenhub-intl.tencentcloudmaas.com` | Global           |
| Guangzhou      | `https://tokenhub.tencentcloudmaas.com`      | Chinese mainland |
| Silicon Valley | `https://tokenhub-us.tencentcloudmaas.com`   | United States    |

**백업 엔드포인트**

기본 주소에 접속할 수 없는 경우 아래 백업 주소로 전환합니다.

| 사이트            | API 주소                                        |
| -------------- | --------------------------------------------- |
| Singapore      | `https://tokenhub-intl.tencentcloudmaas.tech` |
| Guangzhou      | `https://tokenhub.tencentcloudmaas.tech`      |
| Silicon Valley | `https://tokenhub-us.tencentcloudmaas.tech`   |

## 인증 방식

콘솔에서 발급한 API Key를 `Authorization: Bearer` 헤더에 포함합니다.

| 항목    | 값                                                                  |
| ----- | ------------------------------------------------------------------ |
| 헤더    | `Authorization`                                                    |
| 형식    | `Bearer <API_KEY>`                                                 |
| 발급 위치 | [API Key 콘솔 페이지](https://console.tencentcloud.com/tokenhub/apikey) |

## 모델 목록 조회

`GET /v1/models` API로 현재 호출 가능한 모델 목록과 상태를 조회합니다. OpenAI API 프로토콜과 호환되며, 응답의 모델 ID를 추론 API 호출 시 `model` 파라미터에 전달합니다.

**요청 예시**

```bash theme={null}
curl https://tokenhub-intl.tencentcloudmaas.com/v1/models \
  -H "Authorization: Bearer $TOKENHUB_API_KEY"
```

**응답 예시**

```json theme={null}
{
    "object": "list",
    "data": [
        {
            "id": "hy3",
            "object": "model",
            "name": "Hy3",
            "created": 1783267200,
            "status": "online"
        },
        {
            "id": "deepseek-v4-pro",
            "object": "model",
            "name": "DeepSeek-V4-Pro",
            "created": 1776960000,
            "status": "online"
        }
    ]
}
```

**응답 파라미터**

| 파라미터            | 타입      | 설명                                                             |
| --------------- | ------- | -------------------------------------------------------------- |
| object          | String  | `list`로 고정. 모델 목록 응답임을 나타냅니다.                                  |
| data            | Array   | 모델 객체 배열. 각 요소가 호출 가능한 모델 하나를 나타냅니다.                           |
| data\[].id      | String  | 모델 ID. 추론 API 호출 시 `model` 파라미터에 전달하는 값입니다.                    |
| data\[].object  | String  | 객체 타입. `model`로 고정됩니다.                                         |
| data\[].name    | String  | 모델 표시 이름입니다.                                                   |
| data\[].created | Integer | 모델 생성 시각 (Unix timestamp, 초 단위)입니다.                            |
| data\[].status  | String  | 모델 상태입니다. `online` (서비스 중), `pre-offline` (서비스 종료 예정) 값이 있습니다. |

<Warning>
  `/v1/models` 호출 시에도 `Authorization: Bearer <API_KEY>` 헤더가 필요합니다. 인증 정보가 없거나 API Key가 유효하지 않으면 HTTP 401 에러를 반환합니다.
</Warning>

## 모델 호출

언어 모델은 `/v1/chat/completions` 경로로 호출하며, 임베딩 모델은 OpenAI 호환 임베딩 경로로 호출합니다. 호출 가능한 모델 ID와 모델별 지원 기능은 [Model List](/tokenhub/model-list)를 참조하세요.

```bash theme={null}
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "hello"}],
    "stream": true
  }'
```

## 주의사항

* API 에러 응답과 코드는 [API Error Codes](https://www.tencentcloud.com/document/product/1300/82348) 문서를 참조하세요.
* 언어 모델의 상세 파라미터는 [Language Model API](https://www.tencentcloud.com/document/product/1300/80632), 임베딩 모델은 [Embedding Model](https://www.tencentcloud.com/document/product/1300/81297) 문서를 참조하세요.
* `status`가 `pre-offline`인 모델은 서비스 종료 예정이므로 신규 연동에 사용하지 마세요.