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

# ✨ Skill d’intégration API TokenLab

> Installez le skill d’intégration API TokenLab maintenu et apprenez aux coding agents à découvrir les modèles, lire les contrats publics et récupérer des erreurs API.

<Note>
  Cette page documente le skill partagé `tokenlab-api-integration` maintenu. La distribution canonique se trouve dans [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills), où le dépôt public conserve volontairement uniquement ce skill.
</Note>

<Note>
  Cette page couvre l’installation du skill et le workflow agent. Pour la configuration d’un endpoint, utilisez la page SDK, client ou référence API dédiée.
</Note>

## Ce que fait le skill

* Génère des exemples minimaux exécutables pour les familles API TokenLab chat, image, audio, vidéo, traduction et autres.
* Utilise `https://api.tokenlab.sh/v1` pour les clients compatibles OpenAI et explique quand passer aux routes natives Anthropic ou Gemini.
* Découvre les modèles avec `/v1/models`, `/llms.txt` et les listes `recommended_for`, au lieu de deviner depuis des listes obsolètes.
* Lit le détails du modèle d’un modèle avant de relancer les requêtes non-chat afin de ne pas supprimer silencieusement des champs non pris en charge.
* Gère les indices d’erreur Agent-First comme `did_you_mean`, `suggestions`, `retry_after` et `recommended_request`.

## Installation

<Note>
  Utilisez la commande d’installation canonique non interactive :

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

  Cette commande installe le skill partagé `tokenlab-api-integration` depuis le dépôt TokenLab skills.

  Si votre outil ne prend pas en charge l’installer, copiez `skills/tokenlab-api-integration/` depuis le dépôt vers le dossier skills ou rules partagé de votre outil.
</Note>

### Mettre à jour une installation existante

Si vous avez installé le skill avant le nettoyage du dépôt TokenLab, relancez la même commande. Le package public actuel est plus petit et ne dépend plus de scripts de recherche locaux générés.

### Vérifier l’installation

Demandez à votre coding agent :

```
Quelles skills sont disponibles ?
```

Si `tokenlab-api-integration` apparaît, l’installation a réussi.

## Obtenir votre API Key

<Steps>
  <Step title="Visiter TokenLab">
    Allez sur [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="Se connecter">
    Créez un compte ou connectez-vous
  </Step>

  <Step title="Obtenir une API Key">
    Ouvrez [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) et créez une nouvelle key
  </Step>

  <Step title="Copier la key">
    Votre key commence par `sk-...`. Conservez-la en sécurité.
  </Step>
</Steps>

<Tip>
  Ne collez pas les API keys dans les prompts ou les fichiers source. Le skill doit demander quelle variable d’environnement utiliser et générer du code qui lit la key depuis cette variable.
</Tip>

## Workflow Agent recommandé

1. Commencez par le plus petit exemple fonctionnel adapté au langage et à la famille API demandés.
2. Si le choix du modèle est ouvert, appelez `/v1/models` ou `https://api.tokenlab.sh/llms.txt` avant de coder un modèle en dur.
3. Pour les tâches non-chat, appelez `/v1/models?recommended_for=<scene>` où `<scene>` vaut `image`, `video`, `music`, `3d`, `tts`, `stt`, `embedding`, `rerank` ou `translation`.
4. Avant de modifier une requête non-chat échouée, lisez `/v1/models/:model` et alignez `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode` et `recommended_request`.
5. Si l’API renvoie une erreur Agent-First, utilisez les champs structurés pour corriger la requête et ne réessayez que si l’erreur est retryable.

## Exemple chat minimal

Cet exemple utilise le SDK Python OpenAI avec la base URL TokenLab :

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

Exécutez-le avec :

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

## Découverte des modèles et contrats publics

Préférez la découverte en direct aux listes embarquées obsolètes :

```bash theme={null}
# Vue d’ensemble API lisible par machine
curl https://api.tokenlab.sh/llms.txt

# Lister les modèles
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"

# Listes courtes non-chat classées
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"

# Lire le détails du modèle d’un modèle avant de relancer une requête non-chat
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Détail des prix uniquement
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## Conseils de routage natif

Le chemin compatible OpenAI `/v1` est le chemin par défaut pour les exemples courants de chat, Responses, image, embedding, audio et rerank. Utilisez les routes natives Anthropic ou Gemini uniquement si la requête exige un comportement spécifique au fournisseur ou si TokenLab renvoie `X-TokenLab-Native-Endpoint` comme conseil d’optimisation.

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

## Récupération d’erreurs Agent-First

Les erreurs incluent des champs que les coding agents peuvent parser sans scraper la documentation :

| Erreur                                        | Champs utiles                                                                                                                                    | Action de l’agent                                                                                                   |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Nom de modèle incorrect                       | `did_you_mean`, `suggestions`, `hint`                                                                                                            | Réessayer avec le modèle corrigé ou une alternative suggérée                                                        |
| Solde insuffisant                             | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | Demander une approbation ou passer à un modèle abordable                                                            |
| Limite de débit ou indisponibilité temporaire | `retryable`, `retry_after`, `alternatives`                                                                                                       | Attendre, réessayer ou choisir une alternative listée                                                               |
| Contrat non-chat incompatible                 | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | Reconstruire la requête depuis le détails du modèle et return a clear error sur les champs qui changent l’intention |

## Familles API prises en charge

| Famille                 | Chemin principal                                                         |
| ----------------------- | ------------------------------------------------------------------------ |
| Chat et Responses       | `/v1/chat/completions`, `/v1/responses`                                  |
| Messages natifs Claude  | `/v1/messages`                                                           |
| Requêtes natives Gemini | `/v1beta/models/{model}:generateContent`                                 |
| Images                  | `/v1/images/generations`, `/v1/images/edits`                             |
| Vidéo                   | `/v1/videos/generations`                                                 |
| Musique                 | `/v1/music/generations`                                                  |
| Worlds                  | `/v1/worlds/generations` plus endpoints de statut world et media asset   |
| 3D                      | `/v1/3d/generations`                                                     |
| Audio                   | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime                | `/v1/realtime?model={model}`                                             |
| Embeddings et rerank    | `/v1/embeddings`, `/v1/rerank`                                           |
| Traduction de texte     | `/v1/translations`                                                       |

## Bonnes pratiques

<CardGroup cols={2}>
  <Card title="Sécurité des API Keys" icon="shield">
    Utilisez des variables d’environnement et des appels côté serveur. N’exposez jamais les keys dans le code frontend.
  </Card>

  <Card title="Contrat d’abord pour le non-chat" icon="file-code">
    Lisez `/v1/models?recommended_for=...` et `/v1/models/:model` avant de relancer des requêtes image, vidéo, musique, 3D, traduction, audio, embedding ou rerank.
  </Card>

  <Card title="Plus petit exemple exécutable" icon="terminal">
    Produisez un appel fonctionnel avant d’ajouter abstractions, files d’attente ou flows UI.
  </Card>

  <Card title="Utiliser les indices structurés" icon="rotate-cw">
    Parsez `did_you_mean`, `retry_after`, `alternatives` et `recommended_request` avant de modifier le code.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Le skill ne se déclenche pas automatiquement ?">
    Mentionnez “TokenLab” ou “TokenLab API” dans la demande, par exemple : `Utilise TokenLab pour ajouter la génération d’images à mon app Node.js`.
  </Accordion>

  <Accordion title="Quels coding agents sont pris en charge ?">
    Tout coding agent prenant en charge des dossiers partagés de skills ou rules peut utiliser ce dossier. L’installer `skills` gère automatiquement les agents compatibles.
  </Accordion>

  <Accordion title="Comment mettre à jour le skill ?">
    Relancez la commande d’installation. Elle rafraîchit la copie locale depuis le dépôt public canonique.

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

## Ressources

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/fr/guides/agent-first-api">
    Indices d’erreur structurés et comportement de récupération
  </Card>

  <Card title="Documentation API" icon="book" href="https://docs.tokenlab.sh">
    Configuration par endpoint et API Reference
  </Card>

  <Card title="Modèles" icon="sparkles" href="https://tokenlab.sh/fr/models">
    Parcourir les modèles disponibles
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Vue d’ensemble API lisible par machine pour agents
  </Card>
</CardGroup>

<Info>
  Des questions ? Utilisez [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) ou contactez [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>