> ## 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.

# ✨ TokenLab API 통합 스킬

> 관리 중인 TokenLab API 통합 스킬을 설치하고 coding agent가 모델을 찾고 모델 세부정보을 읽으며 API 오류에서 복구하도록 안내합니다.

<Note>
  이 페이지는 관리 중인 공유 `tokenlab-api-integration` 스킬을 설명합니다. 공식 배포 원본은 [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills) 이며 공개 저장소에는 의도적으로 이 스킬만 유지됩니다.
</Note>

<Note>
  이 페이지는 스킬 설치와 agent 워크플로 안내용입니다. 엔드포인트, SDK, 클라이언트 설정은 해당 도구의 전용 통합 페이지나 API Reference를 보세요.
</Note>

## 이 스킬이 하는 일

* TokenLab chat, image, audio, video, translation 및 기타 API 제품군을 위한 최소 실행 예제를 만듭니다.
* OpenAI 호환 클라이언트에는 `https://api.tokenlab.sh/v1`을 사용하고, Anthropic 또는 Gemini 네이티브 라우트로 전환해야 하는 경우를 설명합니다.
* 오래된 목록을 추측하지 않고 `/v1/models`, `/llms.txt`, `recommended_for` 후보로 모델을 탐색합니다.
* 비채팅 요청을 재시도하기 전에 모델 모델 세부정보을 읽어 지원되지 않는 필드가 조용히 제거되지 않게 합니다.
* `did_you_mean`, `suggestions`, `retry_after`, `recommended_request` 같은 Agent-First 오류 힌트를 처리합니다.

## 설치

<Note>
  공식 비대화형 설치 명령을 사용하세요:

  ```bash theme={null}
  npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
  ```

  TokenLab skills 저장소에서 공유 `tokenlab-api-integration` 스킬을 설치합니다.

  도구가 installer를 지원하지 않으면 저장소의 `skills/tokenlab-api-integration/` 폴더를 도구의 공유 skills 또는 rules 디렉터리로 복사하세요.
</Note>

### 기존 설치 업데이트

TokenLab skills 저장소 정리 전에 설치했다면 같은 명령을 다시 실행하세요. 현재 공개 패키지는 더 작고 생성된 로컬 검색 스크립트에 의존하지 않습니다.

### 설치 확인

coding agent에게 물어보세요:

```
사용 가능한 skills는 무엇인가요?
```

`tokenlab-api-integration`이 보이면 설치가 성공한 것입니다.

## API Key 받기

<Steps>
  <Step title="TokenLab 방문">
    [tokenlab.sh](https://tokenlab.sh)로 이동합니다
  </Step>

  <Step title="로그인">
    계정을 만들거나 로그인합니다
  </Step>

  <Step title="API Key 받기">
    [Dashboard → API Keys](https://tokenlab.sh/dashboard/api)를 열고 새 key를 만듭니다
  </Step>

  <Step title="key 복사">
    key는 `sk-...`로 시작합니다. 안전하게 보관하세요.
  </Step>
</Steps>

<Tip>
  API key를 프롬프트나 소스 파일에 붙여 넣지 마세요. 스킬은 사용할 환경 변수를 물어보고 그 변수에서 key를 읽는 코드를 생성해야 합니다.
</Tip>

## 권장 Agent 워크플로

1. 사용자가 요청한 언어와 API 제품군에 맞는 최소 동작 예제부터 시작합니다.
2. 모델 선택이 열려 있으면 모델을 하드코딩하기 전에 `/v1/models` 또는 `https://api.tokenlab.sh/llms.txt`를 호출합니다.
3. 비채팅 작업은 `/v1/models?recommended_for=<scene>`를 호출합니다. `<scene>` 값은 `image`, `video`, `music`, `3d`, `tts`, `stt`, `embedding`, `rerank`, `translation` 중 하나입니다.
4. 실패한 비채팅 요청을 바꾸기 전에 `/v1/models/:model`을 읽고 `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request`에 맞춥니다.
5. API가 Agent-First 오류를 반환하면 구조화 필드로 요청을 수정하고, `retryable`일 때만 재시도합니다.

## 최소 채팅 예제

이 예제는 OpenAI Python SDK와 TokenLab base URL을 사용합니다:

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

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

실행 방법:

```bash theme={null}
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py
```

## 모델 탐색과 모델 세부정보

오래된 번들 목록보다 실시간 탐색을 우선하세요:

```bash theme={null}
# 기계가 읽을 수 있는 API 개요
curl https://api.tokenlab.sh/llms.txt

# 모델 목록
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer sk-KEY"

# 비채팅 추천 후보
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer sk-KEY"

# 비채팅 요청을 재시도하기 전 단일 모델 모델 세부정보 읽기
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# 가격 전용 상세
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## 네이티브 라우팅 힌트

일반적인 chat, Responses, image, embedding, audio, rerank 예제는 OpenAI 호환 `/v1`이 기본 경로입니다. 공급자별 동작이 필요하거나 TokenLab이 최적화 힌트로 `X-TokenLab-Native-Endpoint`를 반환할 때만 Anthropic 또는 Gemini 네이티브 라우트를 사용하세요.

```
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
```

## Agent-First 오류 복구

오류에는 coding agent가 문서를 긁지 않고 파싱할 수 있는 필드가 포함됩니다:

| 오류                 | 유용한 필드                                                                                                                                           | Agent 조치                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| 잘못된 모델 이름          | `did_you_mean`, `suggestions`, `hint`                                                                                                            | 수정된 모델 또는 제안된 대체 모델로 재시도합니다                                 |
| 잔액 부족              | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | 승인을 요청하거나 감당 가능한 모델로 전환합니다                                  |
| 속도 제한 또는 일시적 사용 불가 | `retryable`, `retry_after`, `alternatives`                                                                                                       | 기다렸다가 재시도하거나 나열된 대체 모델을 선택합니다                               |
| 비채팅 계약 불일치         | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | 모델 세부정보에서 요청을 다시 만들고 의도를 바꾸는 필드는 return a clear error 처리합니다 |

## 지원 API 제품군

| 제품군                  | 기본 경로                                                                    |
| -------------------- | ------------------------------------------------------------------------ |
| Chat 및 Responses     | `/v1/chat/completions`, `/v1/responses`                                  |
| Claude 네이티브 messages | `/v1/messages`                                                           |
| Gemini 네이티브 요청       | `/v1beta/models/{model}:generateContent`                                 |
| 이미지                  | `/v1/images/generations`, `/v1/images/edits`                             |
| 비디오                  | `/v1/videos/generations`                                                 |
| 음악                   | `/v1/music/generations`                                                  |
| Worlds               | `/v1/worlds/generations` 및 world 상태와 미디어 asset endpoint                  |
| 3D                   | `/v1/3d/generations`                                                     |
| 오디오                  | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime             | `/v1/realtime?model={model}`                                             |
| Embeddings 및 rerank  | `/v1/embeddings`, `/v1/rerank`                                           |
| 텍스트 번역               | `/v1/translations`                                                       |

## 모범 사례

<CardGroup cols={2}>
  <Card title="API Key 안전" icon="shield">
    환경 변수와 서버 측 호출을 사용하세요. 프런트엔드 코드에 key를 노출하지 마세요.
  </Card>

  <Card title="비채팅은 계약 우선" icon="file-code">
    image, video, music, 3D, translation, audio, embedding, rerank 요청을 재시도하기 전에 `/v1/models?recommended_for=...`와 `/v1/models/:model`을 읽으세요.
  </Card>

  <Card title="최소 실행 예제" icon="terminal">
    추상화, 큐, UI 흐름을 추가하기 전에 먼저 하나의 동작 호출을 만드세요.
  </Card>

  <Card title="구조화 힌트 사용" icon="rotate-cw">
    코드를 변경하기 전에 `did_you_mean`, `retry_after`, `alternatives`, `recommended_request`를 파싱하세요.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="스킬이 자동으로 트리거되지 않나요?">
    요청에 “TokenLab” 또는 “TokenLab API”를 언급하세요. 예: `TokenLab으로 내 Node.js 앱에 이미지 생성을 추가해줘`.
  </Accordion>

  <Accordion title="어떤 coding agent가 지원되나요?">
    공유 skill 또는 rules 디렉터리를 지원하는 모든 coding agent가 이 폴더를 사용할 수 있습니다. `skills` installer는 지원되는 agent를 자동으로 처리합니다.
  </Accordion>

  <Accordion title="스킬을 어떻게 업데이트하나요?">
    설치 명령을 다시 실행하세요. 공식 공개 저장소에서 로컬 사본을 새로 고칩니다.

    ```bash theme={null}
    npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
    ```
  </Accordion>
</AccordionGroup>

## 리소스

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/ko/guides/agent-first-api">
    구조화 오류 힌트와 복구 동작
  </Card>

  <Card title="API 문서" icon="book" href="https://docs.tokenlab.sh">
    엔드포인트별 설정과 API Reference
  </Card>

  <Card title="모델" icon="sparkles" href="https://tokenlab.sh/ko/models">
    사용 가능한 모델 보기
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    agents를 위한 기계 판독 API 개요
  </Card>
</CardGroup>

<Info>
  질문은 [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues)를 사용하거나 [support@tokenlab.sh](mailto:support@tokenlab.sh)로 문의하세요.
</Info>