> ## 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 Integration Skill

> Install the maintained TokenLab API integration skill and teach coding agents to discover models, read model details, and recover from API errors.

<Note>
  This page documents the maintained shared `tokenlab-api-integration` skill. The canonical distribution lives in [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills), where the public repository intentionally keeps only this skill.
</Note>

<Note>
  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.
</Note>

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

<Note>
  Use the canonical non-interactive install command:

  ```bash theme={null}
  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.
</Note>

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

<Steps>
  <Step title="Visit TokenLab">
    Go to [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="Sign In">
    Create an account or log in
  </Step>

  <Step title="Get API Key">
    Open [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) and create a new key
  </Step>

  <Step title="Copy The Key">
    Your key starts with `sk-...`. Store it securely.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## Recommended Agent Workflow

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:

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

Run it with:

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

## Model Discovery

Prefer live discovery over stale bundled lists:

```bash theme={null}
# 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:

| 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

<CardGroup cols={2}>
  <Card title="API Key Safety" icon="shield">
    Use environment variables and server-side calls. Never expose keys in frontend code.
  </Card>

  <Card title="Check Non-Chat Requests" icon="file-code">
    Read `/v1/models?recommended_for=...` and `/v1/models/:model` before retrying image, video, music, 3D, translation, audio, embedding, or rerank requests.
  </Card>

  <Card title="Smallest Runnable Example" icon="terminal">
    Generate one working call before adding abstractions, queues, or UI flows.
  </Card>

  <Card title="Use Structured Hints" icon="rotate-cw">
    Parse `did_you_mean`, `retry_after`, `alternatives`, and `recommended_request` before changing the code.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How do I update the skill?">
    Rerun the install command. It refreshes the local copy from the canonical public repository.

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

## Resources

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/guides/agent-first-api">
    Structured error hints and recovery behavior
  </Card>

  <Card title="API Documentation" icon="book" href="https://docs.tokenlab.sh">
    Endpoint-specific setup and API reference
  </Card>

  <Card title="Models" icon="sparkles" href="https://tokenlab.sh/en/models">
    Browse available models
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Machine-readable API overview for agents
  </Card>
</CardGroup>

<Info>
  Questions? Use [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) or contact [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>