Навыки и интеграция с внешними API
Скрипты навыков могут вызывать внешние HTTP API так же, как обычные программы на Python, тем самым связывая возможности Claude со сторонними сервисами.
Базовый шаблон вызова внешних API
Использование библиотекиrequestsдля отправки HTTP-запросов — самый распространённый способ вызова API в скриптах навыков.
Пример
import requests
import json
import sys
import os
# API-ключ читается из переменных окружения, а не жёстко прописан в скрипте
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:
"""
Универсальная обёртка для вызова API
Параметры:
endpoint: путь API, например, "/analyze"
payload: тело запроса (JSON)
timeout: таймаут в секундах, по умолчанию 30
Возвращает:
Разобранный JSON-ответ или словарь, содержащий ошибку
"""
if not API_KEY:
return {"error": "Ключ API не задан, пожалуйста, установите переменную окружения 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() # Вызывает исключение при HTTP 4xx/5xx
return response.json()
except requests.Timeout:
return {"error": f"Тайм-аут запроса (превышено {timeout} секунд)"}
except requests.HTTPError as e:
return {"error": f"Ошибка HTTP {e.response.status_code}: {e.response.text}"}
except requests.ConnectionError:
return {"error": "Не удалось подключиться к сервису API, пожалуйста, проверьте сеть"}
except Exception as e:
return {"error": str(e)}
# Пример использования
if __name__ == "__main__":
result = call_api("/analyze", {
"text": "example — известная в Китае платформа для технического обучения",
"lang": "zh"
})
print(json.dumps(result, ensure_ascii=False, indent=2))
Безопасное управление ключами API
Ключи API не следует записывать непосредственно в файлы скриптов; их следует передавать через переменные среды.
Пример
export MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
python scripts/api_client.py
# Или задайте их непосредственно при запуске скрипта
MY_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx" python scripts/api_client.py
В SKILL.md сообщите пользователям, что им нужно настроить ключ:
## 前置配置 本 Skill 需要外部 API 密钥,首次使用前请完成以下配置: 1. 在 [API 服务商网站] 注册并获取 API 密钥 2. 在终端中设置环境变量: ```bash export MY_API_KEY="你的密钥" ``` 3. 若需要永久生效,将上述命令添加到 ~/.bashrc 或 ~/.zshrc 若未配置,Skill 将提示"未设置 API 密钥"并退出。
Никогда не коммитьте ключи API в репозиторий Git. Вы можете создать файл .gitignore в каталоге Skill, чтобы исключить файл .env из системы контроля версий.
Обработка ограничения частоты запросов API
Большинство API имеют ограничения на частоту запросов. При пакетном вызове API необходимо добавлять задержки между запросами.
Пример
import time
import requests
class RateLimitedClient:
"""API-клиент с управлением ограничением частоты запросов"""
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 # Минимальный интервал между запросами (секунды)
self.last_request = 0.0
def _wait_if_needed(self):
"""Если с момента последнего запроса прошло недостаточно времени, подождите оставшееся время"""
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
)
# Обработать 429 Too Many Requests: подождать и повторить один раз
if resp.status_code == 429:
retry_after = int(resp.headers.get("Retry-After", 5))
print(f"Сработало ограничение скорости, ожидание {retry_after} секунд перед повторной попыткой...")
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)}
Кэширование ответов
Для API, возвращающих одинаковый результат для одних и тех же входных данных, можно кэшировать результаты в локальные файлы, чтобы избежать повторных запросов, сэкономить деньги и повысить скорость.
Пример
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:
"""Сгенерировать ключ кэша на основе содержимого запроса (хэш 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:
"""
Вызов API с кэшированием
Параметры:
endpoint: путь API
payload: тело запроса
call_fn: функция, которая фактически выполняет HTTP-запрос
Возвращает:
Ответ API (возвращает кэшированный результат напрямую при попадании в кэш)
"""
key = _cache_key(endpoint, payload)
cache_file = os.path.join(CACHE_DIR, f"{key}.json")
# Попадание в кэш
if os.path.exists(cache_file):
with open(cache_file, "r") as f:
print(f"Попадание в кэш: {key[:8]}...")
return json.load(f)
# Промах кэша, выполнить реальный запрос
result = call_fn(endpoint, payload)
# Сохранить в кэш (кэшировать только успешные результаты)
if "error" not in result:
with open(cache_file, "w") as f:
json.dump(result, f, ensure_ascii=False)
return result