Навыки и интеграция с внешними API

Скрипты навыков могут вызывать внешние HTTP API так же, как обычные программы на Python, тем самым связывая возможности Claude со сторонними сервисами.


Базовый шаблон вызова внешних API

Использование библиотекиrequestsдля отправки HTTP-запросов — самый распространённый способ вызова API в скриптах навыков.

Пример

# Путь к файлу: scripts/api_client.py
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 необходимо добавлять задержки между запросами.

Пример

# Путь к файлу: scripts/rate_limited_client.py
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, возвращающих одинаковый результат для одних и тех же входных данных, можно кэшировать результаты в локальные файлы, чтобы избежать повторных запросов, сэкономить деньги и повысить скорость.

Пример

# Путь к файлу: 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:
    """Сгенерировать ключ кэша на основе содержимого запроса (хэш 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
Другие расширения