Skip to main content
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

1

Visit TokenLab

Go to tokenlab.sh
2

Sign In

Create an account or log in
3

Get API Key

Open Dashboard → API Keys and create a new key
4

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.
  1. Start with the smallest working example that matches the user’s requested language and API family.
  2. When model choice is open, call /v1/models or https://api.tokenlab.sh/llms.txt before hardcoding a model.
  3. For non-chat work, call /v1/models?recommended_for=<scene> where <scene> is image, video, music, 3d, tts, stt, embedding, rerank, or translation.
  4. 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.
  5. 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 Routing Hints

OpenAI-compatible /v1 is the default path for common chat, responses, image, embedding, audio, and rerank examples. Use native Anthropic or Gemini routes only when the request needs provider-specific behavior or TokenLab returns X-TokenLab-Native-Endpoint as an optimization hint. 
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

​
Agent-First Error Recovery

Errors include fields that coding agents can parse without scraping docs:
ErrorUseful fieldsAgent action
Wrong model namedid_you_mean, suggestions, hintRetry with the corrected model or one suggested alternative
Insufficient balancebalance_usd, estimated_cost_usd, suggestionsAsk for approval or switch to an affordable model
Rate limit or temporary unavailabilityretryable, retry_after, alternativesWait, retry, or choose a listed alternative
Non-chat unsupported requestsupported_operations, supported_parameters, request_endpoint, request_endpoint_by_operation, request_shape_mode, recommended_requestRebuild the request from the model details and return a clear error on intent-changing fields

​
Supported API Families

FamilyPrimary 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

Mention “TokenLab” or “TokenLab API” in the request, for example: Use TokenLab to add image generation to my Node.js app.
Any coding agent that supports shared skill or rules directories can use the folder. The skills installer handles supported agents automatically.
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.