✨ Skill tích hợp TokenLab API

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, nơi repository công khai chủ ý chỉ giữ skill này.

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ụ đó.

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

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

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

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

Truy cập TokenLab

Đi tới tokenlab.sh

Đăng nhập

Tạo tài khoản hoặc đăng nhập

Lấy API Key

Mở Dashboard → API Keys và tạo key mới

Sao chép key

Key bắt đầu bằng sk-.... Hãy lưu an toàn.

Đừ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 đó.

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

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.
Khi chưa chốt model, gọi /v1/models hoặc https://api.tokenlab.sh/llms.txt trước khi hard-code model.
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.
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.
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:

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:

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ũ:

# 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

An toàn API Key

Dùng biến môi trường và lệnh gọi phía server. Không để lộ keys trong code frontend.

Hợp đồng trước cho non-chat

Đọ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.

Ví dụ chạy được nhỏ nhất

Tạo một lệnh gọi hoạt động trước khi thêm abstraction, queue hoặc luồng UI.

Dùng gợi ý có cấu trúc

Phân tích did_you_mean, retry_after, alternatives và recommended_request trước khi sửa code.

FAQ

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.

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

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.

npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y

Tài nguyên

Agent-First API

Gợi ý lỗi có cấu trúc và hành vi phục hồi

Tài liệu API

Thiết lập theo endpoint và API Reference

Model

Duyệt các model có sẵn

llms.txt

Tổng quan API đọc được bằng máy cho agents

Có câu hỏi? Dùng GitHub Issues hoặc liên hệ support@tokenlab.sh.

​Skill này làm gì

​Cài đặt

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

​Kiểm tra cài đặt

​Lấy API Key

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

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

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

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

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

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

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

An toàn API Key

Hợp đồng trước cho non-chat

Ví dụ chạy được nhỏ nhất

Dùng gợi ý có cấu trúc

​FAQ

​Tài nguyên

Agent-First API

Tài liệu API

Model

llms.txt

Skill này làm gì

Cài đặt

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

Kiểm tra cài đặt

Lấy API Key

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

Ví dụ chat tối thiểu

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

Gợi ý định tuyến native

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

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

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

FAQ

Tài nguyên