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

> Installieren Sie den gepflegten TokenLab API Integration Skill und helfen Sie Coding Agents, Modelle zu entdecken, öffentliche Verträge zu lesen und API-Fehler zu beheben.

<Note>
  Diese Seite dokumentiert den gepflegten gemeinsamen `tokenlab-api-integration` Skill. Die kanonische Distribution liegt in [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills); das öffentliche Repository enthält bewusst nur diesen Skill.
</Note>

<Note>
  Diese Seite ist für Skill-Installation und Agent-Workflow gedacht. Für endpoint-spezifische Einrichtung nutzen Sie die dedizierte SDK-, Client- oder API-Referenzseite.
</Note>

## Was der Skill leistet

* Erstellt minimal lauffähige Beispiele für TokenLab Chat, Bilder, Audio, Video, Übersetzung und weitere API-Familien.
* Nutzt `https://api.tokenlab.sh/v1` für OpenAI-kompatible Clients und erklärt den Wechsel zu nativen Anthropic- oder Gemini-Routen.
* Entdeckt Modelle über `/v1/models`, `/llms.txt` und `recommended_for`-Auswahllisten statt über veraltete Listen.
* Liest vor dem erneuten Versuch von Nicht-Chat-Anfragen den öffentlichen Modelldetails, damit nicht unterstützte Felder nicht still entfernt werden.
* Verarbeitet Agent-First-Hinweise wie `did_you_mean`, `suggestions`, `retry_after` und `recommended_request`.

## Installation

<Note>
  Verwenden Sie den kanonischen nicht interaktiven Installationsbefehl:

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

  Damit wird der gemeinsame `tokenlab-api-integration` Skill aus dem TokenLab skills Repository installiert.

  Wenn Ihr Tool den Installer nicht unterstützt, kopieren Sie `skills/tokenlab-api-integration/` aus dem Repository in das gemeinsame skills- oder rules-Verzeichnis des Tools.
</Note>

### Bestehende Installationen aktualisieren

Wenn Sie den Skill vor der Bereinigung des TokenLab Repository installiert haben, führen Sie denselben Befehl erneut aus. Das aktuelle öffentliche Paket ist kleiner und hängt nicht mehr von generierten lokalen Suchskripten ab.

### Installation prüfen

Fragen Sie Ihren coding agent:

```
Welche skills sind verfügbar?
```

Wenn `tokenlab-api-integration` erscheint, war die Installation erfolgreich.

## API Key abrufen

<Steps>
  <Step title="TokenLab besuchen">
    Öffnen Sie [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="Anmelden">
    Erstellen Sie ein Konto oder melden Sie sich an
  </Step>

  <Step title="API Key abrufen">
    Öffnen Sie [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) und erstellen Sie einen neuen key
  </Step>

  <Step title="key kopieren">
    Ihr key beginnt mit `sk-...`. Bewahren Sie ihn sicher auf.
  </Step>
</Steps>

<Tip>
  Fügen Sie API keys nicht in Prompts oder Quelldateien ein. Der Skill sollte nach der zu verwendenden Umgebungsvariable fragen und Code erzeugen, der den key daraus liest.
</Tip>

## Empfohlener Agent-Workflow

1. Beginnen Sie mit dem kleinsten lauffähigen Beispiel passend zur gewünschten Sprache und API-Familie.
2. Wenn die Modellwahl offen ist, rufen Sie vor dem Hardcoding `/v1/models` oder `https://api.tokenlab.sh/llms.txt` auf.
3. Für Nicht-Chat-Aufgaben rufen Sie `/v1/models?recommended_for=<scene>` auf; `<scene>` ist `image`, `video`, `music`, `3d`, `tts`, `stt`, `embedding`, `rerank` oder `translation`.
4. Vor Änderungen an einer fehlgeschlagenen Nicht-Chat-Anfrage lesen Sie `/v1/models/:model` und gleichen `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode` und `recommended_request` ab.
5. Bei Agent-First-Fehlern nutzen Sie strukturierte Felder zur Korrektur und wiederholen nur, wenn der Fehler retryable ist.

## Minimales Chat-Beispiel

Dieses Beispiel verwendet das OpenAI Python SDK mit der 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)
```

Ausführen mit:

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

## Modellerkennung und öffentliche Verträge

Bevorzugen Sie Live-Erkennung statt veralteter gebündelter Listen:

```bash theme={null}
# Maschinenlesbare API-Übersicht
curl https://api.tokenlab.sh/llms.txt

# Modelle auflisten
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"

# Sortierte Nicht-Chat-Auswahllisten
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"

# Vor dem erneuten Versuch einer Nicht-Chat-Anfrage den Modelldetails eines Modells lesen
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Nur Preisdetails
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## Hinweise zum nativen Routing

Der OpenAI-kompatible Pfad `/v1` ist der Standard für gängige Chat-, Responses-, Bild-, Embedding-, Audio- und Rerank-Beispiele. Nutzen Sie native Anthropic- oder Gemini-Routen nur, wenn die Anfrage anbieterspezifisches Verhalten benötigt oder TokenLab `X-TokenLab-Native-Endpoint` als Optimierungshinweis zurückgibt.

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

## Agent-First Fehlerbehebung

Fehler enthalten Felder, die coding agents ohne Auslesen der Dokumentation parsen können:

| Fehler                                            | Nützliche Felder                                                                                                                                 | Agent-Aktion                                                                                         |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Falscher Modellname                               | `did_you_mean`, `suggestions`, `hint`                                                                                                            | Mit korrigiertem Modell oder einer vorgeschlagenen Alternative erneut versuchen                      |
| Unzureichendes Guthaben                           | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | Bestätigung einholen oder auf ein günstigeres Modell wechseln                                        |
| Rate Limit oder vorübergehende Nichtverfügbarkeit | `retryable`, `retry_after`, `alternatives`                                                                                                       | Warten, erneut versuchen oder eine gelistete Alternative wählen                                      |
| Nicht-Chat-Vertragskonflikt                       | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | Anfrage aus dem Modelldetails neu bauen und intent-verändernde Felder return a clear error behandeln |

## Unterstützte API-Familien

| Familie                | Primärer Pfad                                                            |
| ---------------------- | ------------------------------------------------------------------------ |
| Chat und Responses     | `/v1/chat/completions`, `/v1/responses`                                  |
| Claude-native messages | `/v1/messages`                                                           |
| Gemini-native Anfragen | `/v1beta/models/{model}:generateContent`                                 |
| Bilder                 | `/v1/images/generations`, `/v1/images/edits`                             |
| Video                  | `/v1/videos/generations`                                                 |
| Musik                  | `/v1/music/generations`                                                  |
| Worlds                 | `/v1/worlds/generations` plus world-Status und Medien-Asset-Endpunkte    |
| 3D                     | `/v1/3d/generations`                                                     |
| Audio                  | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime               | `/v1/realtime?model={model}`                                             |
| Embeddings und Rerank  | `/v1/embeddings`, `/v1/rerank`                                           |
| Textübersetzung        | `/v1/translations`                                                       |

## Best Practices

<CardGroup cols={2}>
  <Card title="API-Key-Sicherheit" icon="shield">
    Nutzen Sie Umgebungsvariablen und serverseitige Aufrufe. Geben Sie keys nie im Frontend-Code preis.
  </Card>

  <Card title="Vertrag zuerst für Nicht-Chat" icon="file-code">
    Lesen Sie `/v1/models?recommended_for=...` und `/v1/models/:model`, bevor Sie Bild-, Video-, Musik-, 3D-, Übersetzungs-, Audio-, Embedding- oder Rerank-Anfragen erneut versuchen.
  </Card>

  <Card title="Kleinstes lauffähiges Beispiel" icon="terminal">
    Erzeugen Sie zuerst einen funktionierenden Aufruf, bevor Sie Abstraktionen, Queues oder UI-Flows hinzufügen.
  </Card>

  <Card title="Strukturierte Hinweise nutzen" icon="rotate-cw">
    Parsen Sie `did_you_mean`, `retry_after`, `alternatives` und `recommended_request`, bevor Sie Code ändern.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Skill wird nicht automatisch ausgelöst?">
    Erwähnen Sie “TokenLab” oder “TokenLab API” in der Anfrage, zum Beispiel: `Nutze TokenLab, um Bildgenerierung in meine Node.js-App einzubauen`.
  </Accordion>

  <Accordion title="Welche coding agents werden unterstützt?">
    Jeder coding agent mit gemeinsamem skill- oder rules-Verzeichnis kann den Ordner verwenden. Der `skills` Installer behandelt unterstützte agents automatisch.
  </Accordion>

  <Accordion title="Wie aktualisiere ich den Skill?">
    Führen Sie den Installationsbefehl erneut aus. Dadurch wird die lokale Kopie aus dem kanonischen öffentlichen Repository aktualisiert.

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

## Ressourcen

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/de/guides/agent-first-api">
    Strukturierte Fehlerhinweise und Wiederherstellungsverhalten
  </Card>

  <Card title="API-Dokumentation" icon="book" href="https://docs.tokenlab.sh">
    Endpoint-spezifische Einrichtung und API Reference
  </Card>

  <Card title="Modelle" icon="sparkles" href="https://tokenlab.sh/de/models">
    Verfügbare Modelle durchsuchen
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Maschinenlesbare API-Übersicht für agents
  </Card>
</CardGroup>

<Info>
  Fragen? Nutzen Sie [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) oder kontaktieren Sie [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>