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

# ✨ Skill tích hợp TokenLab API

> Cài skill tích hợp TokenLab API đang được duy trì và hướng dẫn coding agent khám phá model, đọc chi tiết model và phục hồi từ lỗi API.

<Note>
  Trang này mô tả skill dùng chung `tokenlab-api-integration` đang được duy trì. Bản phân phối chuẩn nằm ở [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills), nơi repository công khai chủ ý chỉ giữ skill này.
</Note>

<Note>
  Dùng trang này để cài skill và hướng dẫn workflow cho agent. Với thiết lập theo endpoint, hãy dùng trang SDK, client hoặc API reference riêng của công cụ đó.
</Note>

## Skill này làm gì

* Tạo ví dụ tối thiểu chạy được cho các nhóm API TokenLab như chat, image, audio, video, translation và nhiều nhóm khác.
* Dùng `https://api.tokenlab.sh/v1` cho client tương thích OpenAI và giải thích khi nào nên chuyển sang route native Anthropic hoặc Gemini.
* Khám phá model bằng `/v1/models`, `/llms.txt` và danh sách `recommended_for` thay vì đoán từ danh sách cũ.
* Đọc chi tiết model của model trước khi thử lại yêu cầu non-chat để không âm thầm bỏ các trường không hỗ trợ.
* Xử lý gợi ý lỗi Agent-First như `did_you_mean`, `suggestions`, `retry_after` và `recommended_request`.

## Cài đặt

<Note>
  Dùng lệnh cài đặt chuẩn không tương tác:

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

  Lệnh này cài skill dùng chung `tokenlab-api-integration` từ repository TokenLab skills.

  Nếu công cụ của bạn không hỗ trợ installer, hãy sao chép `skills/tokenlab-api-integration/` từ repository vào thư mục skills hoặc rules dùng chung của công cụ.
</Note>

### Cập nhật bản cài hiện có

Nếu bạn đã cài skill trước đó, hãy chạy lại cùng lệnh để cập nhật lên gói public hiện tại.

### Kiểm tra cài đặt

Hỏi coding agent của bạn:

```
Có những skills nào?
```

Nếu thấy `tokenlab-api-integration`, cài đặt đã thành công.

## Lấy API Key

<Steps>
  <Step title="Truy cập TokenLab">
    Đi tới [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="Đăng nhập">
    Tạo tài khoản hoặc đăng nhập
  </Step>

  <Step title="Lấy API Key">
    Mở [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) và tạo key mới
  </Step>

  <Step title="Sao chép key">
    Key bắt đầu bằng `sk-...`. Hãy lưu an toàn.
  </Step>
</Steps>

<Tip>
  Đừng dán API keys vào prompt hoặc file nguồn. Skill nên hỏi biến môi trường nào sẽ dùng và tạo code đọc key từ biến đó.
</Tip>

## Quy trình Agent được khuyến nghị

1. Bắt đầu với ví dụ chạy được nhỏ nhất khớp với ngôn ngữ và nhóm API người dùng yêu cầu.
2. Khi chưa chốt model, gọi `/v1/models` hoặc `https://api.tokenlab.sh/llms.txt` trước khi hard-code model.
3. Với tác vụ non-chat, gọi `/v1/models?recommended_for=<scene>` trong đó `<scene>` là `image`, `video`, `music`, `3d`, `tts`, `stt`, `embedding`, `rerank` hoặc `translation`.
4. Trước khi đổi một yêu cầu non-chat bị lỗi, đọc `/v1/models/:model` và căn theo `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request`.
5. Nếu API trả lỗi Agent-First, dùng trường có cấu trúc để sửa yêu cầu và chỉ thử lại khi lỗi retryable.

## Ví dụ chat tối thiểu

Ví dụ này dùng OpenAI Python SDK với base URL của TokenLab:

```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)
```

Chạy bằng:

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

## Khám phá model và chi tiết model

Ưu tiên khám phá trực tiếp thay vì danh sách đóng gói đã cũ:

```bash theme={null}
# Tổng quan API đọc được bằng máy
curl https://api.tokenlab.sh/llms.txt

# Liệt kê model
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"

# Danh sách đề xuất có xếp hạng cho non-chat
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"

# Đọc chi tiết model của một model trước khi thử lại yêu cầu non-chat
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Chi tiết chỉ về giá
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## Gợi ý định tuyến native

Đường dẫn tương thích OpenAI `/v1` là mặc định cho ví dụ chat, Responses, image, embedding, audio và rerank phổ biến. Chỉ dùng route native Anthropic hoặc Gemini khi yêu cầu cần hành vi đặc thù của nhà cung cấp hoặc TokenLab trả về `X-TokenLab-Native-Endpoint` như một gợi ý tối ưu.

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

## Phục hồi lỗi Agent-First

Lỗi bao gồm các trường mà coding agent có thể phân tích mà không cần đọc thủ công tài liệu:

| Lỗi                                          | Trường hữu ích                                                                                                                                   | Hành động của agent                                                                  |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Sai tên model                                | `did_you_mean`, `suggestions`, `hint`                                                                                                            | Thử lại với model đã sửa hoặc một lựa chọn thay thế được gợi ý                       |
| Không đủ số dư                               | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | Xin xác nhận hoặc chuyển sang model phù hợp chi phí                                  |
| Giới hạn tốc độ hoặc tạm thời không khả dụng | `retryable`, `retry_after`, `alternatives`                                                                                                       | Chờ rồi thử lại hoặc chọn một lựa chọn thay thế được liệt kê                         |
| Hợp đồng non-chat không khớp                 | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | Dựng lại yêu cầu từ chi tiết model và return a clear error với trường làm đổi ý định |

## Các nhóm API được hỗ trợ

| Nhóm                   | Đường dẫn chính                                                          |
| ---------------------- | ------------------------------------------------------------------------ |
| Chat và Responses      | `/v1/chat/completions`, `/v1/responses`                                  |
| Claude-native messages | `/v1/messages`                                                           |
| Yêu cầu Gemini-native  | `/v1beta/models/{model}:generateContent`                                 |
| Hình ảnh               | `/v1/images/generations`, `/v1/images/edits`                             |
| Video                  | `/v1/videos/generations`                                                 |
| Nhạc                   | `/v1/music/generations`                                                  |
| Worlds                 | `/v1/worlds/generations` cùng endpoint trạng thái world và media asset   |
| 3D                     | `/v1/3d/generations`                                                     |
| Âm thanh               | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime               | `/v1/realtime?model={model}`                                             |
| Embeddings và rerank   | `/v1/embeddings`, `/v1/rerank`                                           |
| Dịch văn bản           | `/v1/translations`                                                       |

## Thực hành tốt nhất

<CardGroup cols={2}>
  <Card title="An toàn API Key" icon="shield">
    Dùng biến môi trường và lệnh gọi phía server. Không để lộ keys trong code frontend.
  </Card>

  <Card title="Hợp đồng trước cho non-chat" icon="file-code">
    Đọc `/v1/models?recommended_for=...` và `/v1/models/:model` trước khi thử lại yêu cầu image, video, music, 3D, translation, audio, embedding hoặc rerank.
  </Card>

  <Card title="Ví dụ chạy được nhỏ nhất" icon="terminal">
    Tạo một lệnh gọi hoạt động trước khi thêm abstraction, queue hoặc luồng UI.
  </Card>

  <Card title="Dùng gợi ý có cấu trúc" icon="rotate-cw">
    Phân tích `did_you_mean`, `retry_after`, `alternatives` và `recommended_request` trước khi sửa code.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Skill không tự kích hoạt?">
    Nhắc “TokenLab” hoặc “TokenLab API” trong yêu cầu, ví dụ: `Dùng TokenLab để thêm tạo ảnh vào app Node.js của tôi`.
  </Accordion>

  <Accordion title="Hỗ trợ coding agent nào?">
    Bất kỳ coding agent nào hỗ trợ thư mục skill hoặc rules dùng chung đều dùng được thư mục này. Installer `skills` tự xử lý các agent được hỗ trợ.
  </Accordion>

  <Accordion title="Cập nhật skill thế nào?">
    Chạy lại lệnh cài đặt. Lệnh này làm mới bản sao cục bộ từ repository công khai chuẩn.

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

## Tài nguyên

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/vi/guides/agent-first-api">
    Gợi ý lỗi có cấu trúc và hành vi phục hồi
  </Card>

  <Card title="Tài liệu API" icon="book" href="https://docs.tokenlab.sh">
    Thiết lập theo endpoint và API Reference
  </Card>

  <Card title="Model" icon="sparkles" href="https://tokenlab.sh/vi/models">
    Duyệt các model có sẵn
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Tổng quan API đọc được bằng máy cho agents
  </Card>
</CardGroup>

<Info>
  Có câu hỏi? Dùng [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) hoặc liên hệ [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>