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