Integración de Skills con API externas

Los scripts de Skill pueden llamar a APIs HTTP externas como un programa Python normal, conectando así las capacidades de Claude con servicios de terceros.


Patrón básico para llamar a APIs externas

Usandorequestsla biblioteca para enviar solicitudes HTTP es la forma más común de llamar a APIs en los scripts de Skill.

Ejemplo

# Ruta de archivo: scripts/api_client.py
import requests
import json
import sys
import os

# La clave de API se lee de variables de entorno, no se codifica en el 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:
    """
Envoltura genérica de llamadas a API

Parámetros:
endpoint: ruta de API, como "/analyze"
payload: cuerpo de la solicitud (JSON)
timeout: segundos de tiempo de espera, por defecto 30

Devuelve:
Respuesta JSON analizada, o un diccionario que contiene error
    """

    if not API_KEY:
        return {"error": "Clave de API no configurada, por favor establece la variable de entorno 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()   # Lanza una excepción en HTTP 4xx/5xx
        return response.json()

    except requests.Timeout:
        return {"error": f"Tiempo de espera agotado (más de {timeout} segundos)"}
    except requests.HTTPError as e:
        return {"error": f"Error HTTP {e.response.status_code}: {e.response.text}"}
    except requests.ConnectionError:
        return {"error": "No se pudo conectar al servicio de API, verifica la red"}
    except Exception as e:
        return {"error": str(e)}

# Ejemplo de uso
if __name__ == "__main__":
    result = call_api("/analyze", {
        "text": "ejemplo es una plataforma de aprendizaje técnico muy conocida en China",
        "lang": "zh"
    })
    print(json.dumps(result, ensure_ascii=False, indent=2))

Gestión segura de claves de API

Las claves de API no deben escribirse directamente en los archivos de script; deben pasarse mediante variables de entorno.

Ejemplo

# Configurar la variable de entorno antes de ejecutar el script
export MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
python scripts/api_client.py

# O configurarla en línea al ejecutar el script
MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx" python scripts/api_client.py

En SKILL.md, informa al usuario de que necesita configurar la clave:

## 前置配置

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

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

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

Nunca envíes las claves de API a un repositorio de Git. Puedes crear un archivo .gitignore en el directorio de Skill para excluir el archivo .env del control de versiones.


Manejo del límite de velocidad de API (Rate Limiting)

La mayoría de las API tienen límites de frecuencia de solicitudes. Al llamar a las API en lotes, es necesario añadir demoras entre las solicitudes.

Ejemplo

# Ruta de archivo: scripts/rate_limited_client.py
import time
import requests

class RateLimitedClient:
    """Cliente de API con control de límite de velocidad"""

    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  # Intervalo mínimo entre solicitudes (segundos)
        self.last_request = 0.0

    def _wait_if_needed(self):
        """Si el tiempo desde la última solicitud es insuficiente, espera el tiempo restante"""
        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
            )
            # Manejar 429 Too Many Requests: esperar y reintentar una vez
            if resp.status_code == 429:
                retry_after = int(resp.headers.get("Retry-After", 5))
                print(f"Límite de velocidad activado, esperando {retry_after} segundos para reintentar...")
                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)}

Caché de resultados de respuesta

Para las API que devuelven el mismo resultado ante la misma entrada, puedes almacenar el resultado en caché en un archivo local para evitar solicitudes repetidas, lo que ahorra dinero y acelera el proceso.

Ejemplo

# Ruta de archivo: 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:
    """Generar clave de caché (hash MD5) según el contenido de la solicitud"""
    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:
    """
Llamada a API con caché

Parámetros:
endpoint: ruta de API
payload: cuerpo de la solicitud
call_fn: función que realmente realiza la solicitud HTTP

Devuelve:
Respuesta de API (si se acierta en caché, devuelve directamente el resultado en caché)
    """

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

    # Acierto de caché
    if os.path.exists(cache_file):
        with open(cache_file, "r") as f:
            print(f"Caché acertada: {key[:8]}...")
            return json.load(f)

    # No acertada, realizar la solicitud real
    result = call_fn(endpoint, payload)

    # Guardar en caché (solo almacenar resultados exitosos)
    if "error" not in result:
        with open(cache_file, "w") as f:
            json.dump(result, f, ensure_ascii=False)

    return result
Otras extensiones