Skills et intégration des API externes

Les scripts Skill peuvent appeler des API HTTP externes comme des programmes Python ordinaires, ce qui permet de connecter les capacités de Claude à des services tiers.


Modèle de base pour appeler des API externes

L'utilisation de la bibliothèquerequestspour envoyer des requêtes HTTP est la manière la plus courante d'appeler des API dans les scripts Skill.

Exemple

# Chemin du fichier : scripts/api_client.py
import requests
import json
import sys
import os

# La clé API est lue depuis les variables d'environnement, et non codée en dur dans le script
API_KEY = os.environ.get("MY_API_KEY", "")
BASE_URL = "https://api.example.com/v1"

def call_api(endpoint: str, payload: dict, timeout: int = 30) -> dict:
    """
Wrapper générique d'appel API

Paramètres :
endpoint: chemin d'API, par exemple, "/analyze"
payload: corps de la requête (JSON)
timeout: délai d'attente en secondes, par défaut 30

Retourne :
Réponse JSON analysée, ou un dictionnaire contenant une erreur
    """

    if not API_KEY:
        return {"error": "Clé API non définie, veuillez définir la variable d'environnement MY_API_KEY"}

    url = BASE_URL + endpoint
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type":  "application/json"
    }

    try:
        response = requests.post(url, headers=headers,
                                 json=payload, timeout=timeout)
        response.raise_for_status()   # Lève une exception sur HTTP 4xx/5xx
        return response.json()

    except requests.Timeout:
        return {"error": f"Délai d'attente de la requête dépassé ({timeout} secondes)"}
    except requests.HTTPError as e:
        return {"error": f"Erreur HTTP {e.response.status_code} : {e.response.text}"}
    except requests.ConnectionError:
        return {"error": "Impossible de se connecter au service API, veuillez vérifier le réseau"}
    except Exception as e:
        return {"error": str(e)}

# Exemple d'utilisation
if __name__ == "__main__":
    result = call_api("/analyze", {
        "text": "example est une plateforme d'apprentissage technique bien connue en Chine",
        "lang": "zh"
    })
    print(json.dumps(result, ensure_ascii=False, indent=2))

Gestion sécurisée des clés API

Les clés API ne doivent pas être écrites directement dans les fichiers de script ; elles doivent être transmises via des variables d'environnement.

Exemple

# Définir les variables d'environnement avant d'exécuter le script
export MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
python scripts/api_client.py

# Ou les définir directement lors de l'exécution du script
MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx" python scripts/api_client.py

Dans SKILL.md, informez les utilisateurs qu'ils doivent configurer la clé :

## 前置配置

本 Skill 需要外部 API 密钥,首次使用前请完成以下配置:

1. 在 [API 服务商网站] 注册并获取 API 密钥
2. 在终端中设置环境变量:
   ```bash
   export MY_API_KEY="你的密钥"
   ```
3. 若需要永久生效,将上述命令添加到 ~/.bashrc 或 ~/.zshrc

若未配置,Skill 将提示"未设置 API 密钥"并退出。

Ne validez jamais de clés API dans un dépôt Git. Vous pouvez créer un fichier .gitignore dans le répertoire de la Skill pour exclure le fichier .env du contrôle de version.


Gestion de la limitation de débit des API

La plupart des API ont des limites de fréquence de requêtes. Lorsque vous appelez des API par lots, vous devez ajouter des délais entre les requêtes.

Exemple

# Chemin du fichier : scripts/rate_limited_client.py
import time
import requests

class RateLimitedClient:
    """Client API avec contrôle de la limitation de débit"""

    def __init__(self, base_url: str, api_key: str,
                 requests_per_minute: int = 60):
        self.base_url    = base_url
        self.api_key     = api_key
        self.min_interval = 60.0 / requests_per_minute  # Intervalle minimum entre les requêtes (secondes)
        self.last_request = 0.0

    def _wait_if_needed(self):
        """Si le temps écoulé depuis la dernière requête n'est pas suffisant, attendre le temps restant"""
        elapsed = time.time() - self.last_request
        wait    = self.min_interval - elapsed
        if wait > 0:
            time.sleep(wait)
        self.last_request = time.time()

    def post(self, endpoint: str, payload: dict) -> dict:
        self._wait_if_needed()
        headers = {"Authorization": f"Bearer {self.api_key}"}
        try:
            resp = requests.post(
                self.base_url + endpoint,
                headers=headers, json=payload, timeout=30
            )
            # Gérer 429 Too Many Requests: attendre et réessayer une fois
            if resp.status_code == 429:
                retry_after = int(resp.headers.get("Retry-After", 5))
                print(f"Limite de débit atteinte, attente de {retry_after} secondes avant de réessayer...")
                time.sleep(retry_after)
                resp = requests.post(
                    self.base_url + endpoint,
                    headers=headers, json=payload, timeout=30
                )
            resp.raise_for_status()
            return resp.json()
        except Exception as e:
            return {"error": str(e)}

Mise en cache des réponses

Pour les API qui renvoient le même résultat pour la même entrée, vous pouvez mettre en cache les résultats dans des fichiers locaux afin d'éviter les requêtes en double, ce qui permet d'économiser de l'argent et d'améliorer la vitesse.

Exemple

# Chemin du fichier : scripts/cached_api.py
import hashlib
import json
import os

CACHE_DIR = "/home/claude/.api_cache"
os.makedirs(CACHE_DIR, exist_ok=True)

def _cache_key(endpoint: str, payload: dict) -> str:
    """Générer une clé de cache en fonction du contenu de la requête (hash MD5)"""
    raw = json.dumps({"endpoint": endpoint, "payload": payload},
                     sort_keys=True)
    return hashlib.md5(raw.encode()).hexdigest()

def cached_call(endpoint: str, payload: dict, call_fn) -> dict:
    """
Appel API avec mise en cache

Paramètres :
endpoint : chemin de l'API
payload : corps de la requête
call_fn : la fonction qui effectue réellement la requête HTTP

Retourne :
Réponse API (renvoie directement le résultat mis en cache lorsque le cache est atteint)
    """

    key       = _cache_key(endpoint, payload)
    cache_file = os.path.join(CACHE_DIR, f"{key}.json")

    # Succès du cache
    if os.path.exists(cache_file):
        with open(cache_file, "r") as f:
            print(f"Cache trouvé : {key[:8]}...")
            return json.load(f)

    # Défaut de cache, effectuer une vraie requête
    result = call_fn(endpoint, payload)

    # Enregistrer dans le cache (ne mettre en cache que les résultats réussis)
    if "error" not in result:
        with open(cache_file, "w") as f:
            json.dump(result, f, ensure_ascii=False)

    return result
Autres extensions