✨ TokenLab API Integration Skill

This page documents the maintained shared tokenlab-api-integration skill. The canonical distribution lives in hedging8563/tokenlab-skills, where the public repository intentionally keeps only this skill.

Use this page for skill installation and agent workflow guidance. For endpoint-specific setup, use the dedicated SDK, client, or API reference page for that tool.

What The Skill Does

Generates minimal runnable examples for TokenLab chat, image, audio, video, translation, and other API families.
Uses https://api.tokenlab.sh/v1 for OpenAI-compatible clients and explains when to switch to native Anthropic or Gemini routes.
Discovers models with /v1/models, /llms.txt, and recommended_for shortlists instead of guessing from stale lists.
Reads a model details before retrying non-chat requests, so unsupported fields are not silently dropped.
Handles Agent-First error hints such as did_you_mean, suggestions, retry_after, and recommended_request.

Install

Use the canonical non-interactive install command:

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

This installs the shared tokenlab-api-integration skill from the TokenLab skills repository.If your tool does not support the installer, copy skills/tokenlab-api-integration/ from the repository into your tool’s shared skills or rules directory.

Update Existing Installs

If you installed the skill earlier, rerun the same command to update to the current public package.

Verify Installation

Ask your coding agent:

What skills are available?

If you see tokenlab-api-integration, the installation succeeded.

Get Your API Key

Visit TokenLab

Go to tokenlab.sh

Create an account or log in

Get API Key

Open Dashboard → API Keys and create a new key

Copy The Key

Your key starts with sk-.... Store it securely.

Do not paste API keys into prompts or source files. The skill should ask which environment variable to use and generate code that reads the key from that variable.

Recommended Agent Workflow

Start with the smallest working example that matches the user’s requested language and API family.
When model choice is open, call /v1/models or https://api.tokenlab.sh/llms.txt before hardcoding a model.
For non-chat work, call /v1/models?recommended_for=<scene> where <scene> is image, video, music, 3d, tts, stt, embedding, rerank, or translation.
Before changing a failed non-chat request, read /v1/models/:model and align with supported_operations, supported_parameters, request_endpoint, request_endpoint_by_operation, request_shape_mode, and recommended_request.
If the API returns an Agent-First error, use the structured fields to correct the request and retry only when the error is retryable.

Minimal Chat Example

This example uses the OpenAI Python SDK with the TokenLab base URL:

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)

Run it with:

pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py

Model Discovery

Prefer live discovery over stale bundled lists:

# Machine-readable API overview
curl https://api.tokenlab.sh/llms.txt

# List models
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"

# Ranked non-chat shortlists
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"

# Read one model details before retrying non-chat requests
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Pricing-only detail
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"

Native Protocol Selection

OpenAI-compatible /v1 is the default path for common chat, image, embedding, audio, and rerank examples. Do not infer native protocol availability from a model or provider name, or from Chat response headers. Read GET /v1/models/{model} and use only a format listed in tokenlab.accepted_request_formats. The protocol endpoints are Chat Completions at /v1/chat/completions, Responses at /v1/responses, Messages at /v1/messages, and Gemini at /v1beta/models/{model}:generateContent.

Agent-First Error Recovery

Errors include fields that coding agents can parse without scraping docs:

Error	Useful fields	Agent action
Wrong model name	`did_you_mean`, `suggestions`, `hint`	Retry with the corrected model or one suggested alternative
Insufficient balance	`balance_usd`, `estimated_cost_usd`, `suggestions`	Ask for approval or switch to an affordable model
Rate limit or temporary unavailability	`retryable`, `retry_after`, `alternatives`	Wait, retry, or choose a listed alternative
Non-chat unsupported request	`supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request`	Rebuild the request from the model details and return a clear error on intent-changing fields

Supported API Families

Family	Primary path
Chat and Responses	`/v1/chat/completions`, `/v1/responses`
Claude-native messages	`/v1/messages`
Gemini-native requests	`/v1beta/models/{model}:generateContent`
Images	`/v1/images/generations`, `/v1/images/edits`
Video	`/v1/videos/generations`
Music	`/v1/music/generations`
Worlds	`/v1/worlds/generations` plus world status and media asset endpoints
3D	`/v1/3d/generations`
Audio	`/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations`
Realtime	`/v1/realtime?model={model}`
Embeddings and rerank	`/v1/embeddings`, `/v1/rerank`
Text translation	`/v1/translations`

Best Practices

API Key Safety

Use environment variables and server-side calls. Never expose keys in frontend code.

Check Non-Chat Requests

Read /v1/models?recommended_for=... and /v1/models/:model before retrying image, video, music, 3D, translation, audio, embedding, or rerank requests.

Smallest Runnable Example

Generate one working call before adding abstractions, queues, or UI flows.

Use Structured Hints

Parse did_you_mean, retry_after, alternatives, and recommended_request before changing the code.

FAQ

Skill not triggering automatically?

Mention “TokenLab” or “TokenLab API” in the request, for example: Use TokenLab to add image generation to my Node.js app.

Which coding agents are supported?

Any coding agent that supports shared skill or rules directories can use the folder. The skills installer handles supported agents automatically.

How do I update the skill?

Rerun the install command. It refreshes the local copy from the canonical public repository.

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

Resources

Agent-First API

Structured error hints and recovery behavior

API Documentation

Endpoint-specific setup and API reference

Models

Browse available models

llms.txt

Machine-readable API overview for agents

Questions? Use GitHub Issues or contact support@tokenlab.sh.

Getting Started

Core Guides

Media Guides

✨ TokenLab API Integration Skill

What The Skill Does

Install

Update Existing Installs

Verify Installation

Get Your API Key

Recommended Agent Workflow

Minimal Chat Example

Model Discovery

Native Protocol Selection

Agent-First Error Recovery

Supported API Families

Best Practices

API Key Safety

Check Non-Chat Requests

Smallest Runnable Example

Use Structured Hints

FAQ

Resources

Agent-First API

API Documentation

Models

llms.txt

​What The Skill Does

​Install

​Update Existing Installs

​Verify Installation

​Get Your API Key

​Recommended Agent Workflow

​Minimal Chat Example

​Model Discovery

​Native Protocol Selection

​Agent-First Error Recovery

​Supported API Families

​Best Practices

API Key Safety

Check Non-Chat Requests

Smallest Runnable Example

Use Structured Hints

​FAQ

​Resources

Agent-First API

API Documentation

Models

llms.txt

What The Skill Does

Install

Update Existing Installs

Verify Installation

Get Your API Key

Recommended Agent Workflow

Minimal Chat Example

Model Discovery

Native Protocol Selection

Agent-First Error Recovery

Supported API Families

Best Practices

FAQ

Resources