Агенты и автоматизация

Это руководство предназначено для ИИ-агентов разработки и автоматизированных серверных систем, подключающих SpicyAPI. Оно превращает API Reference в ограниченный по времени, возобновляемый и проверяемый процесс: найти контракт, проверить входные данные, создать задачу один раз, безопасно дождаться результата, подтвердить итоговый статус и сохранить файлы до истечения срока.

Машиночитаемые точки обнаружения

Сначала читайте самый небольшой ресурс, отвечающий на текущий вопрос. Это экономит контекст и снижает риск устаревших предположений.

Считайте OpenAPI и актуальный каталог моделей контрактом. Маркетинговые примеры не заменяют Schema. Обновляйте сохранённые discovery-файлы перед генерацией кода и при появлении новых ошибок валидации.

Официальные npm-интеграции

SDK, CLI, MCP и переносимый Agent Skill — четыре независимых npm-пакета под лицензией MIT. Устанавливайте только нужный интерфейс. @spicyapi/skill использует переносимый формат Agent Skills и не ограничен Codex.

npm install @spicyapi/sdk
npx --yes --package=@spicyapi/cli spicyapi --help
npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx --yes --package=@spicyapi/skill spicyapi-skill install

По умолчанию Skill устанавливается в ~/.agents/skills/spicyapi. Если Agent использует другой каталог Skills, укажите точное назначение через --target /точный/путь/spicyapi.

Использование в кодовом агенте

MCP-сервер работает локально через stdio и передаёт агенту каталог моделей, расчёт стоимости, создание задач и получение результата. Любое платное действие останавливается на подтверждении, которое агент не может обойти. Ниже — вид, который сейчас рекомендует каждый клиент; расположение и формат конфигурации задаёт сам клиент, и они меняются между версиями, поэтому опирайтесь на их документацию.

Claude Code

claude mcp add spicyapi \
  -e SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

npx --yes --package=@spicyapi/skill spicyapi-skill install \
  --target ~/.claude/skills/spicyapi

Codex CLI

codex mcp add spicyapi \
  --env SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

npx --yes --package=@spicyapi/skill spicyapi-skill install \
  --target ~/.codex/skills/spicyapi

Обе команды переносят SPICY_API_KEY из текущей оболочки в локальную конфигурацию клиента, поэтому запускайте их в терминале, где ключ уже экспортирован. Ключ остаётся на вашей машине — не коммитьте его.

Cursor, Windsurf и Gemini CLI

Их файлы конфигурации — ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json и ~/.gemini/settings.json; структура одинаковая:

{
  "mcpServers": {
    "spicyapi": {
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "YOUR_SERVER_SIDE_KEY" }
    }
  }
}

Это пользовательские файлы вне репозитория. После замены YOUR_SERVER_SIDE_KEY на настоящий ключ не копируйте этот блок в файлы проекта, попадающие в систему контроля версий.

VS Code

.vscode/mcp.json коммитится вместе с репозиторием, поэтому ключа в нём быть не должно. Пусть VS Code запросит значение при первом запуске сервера и сохранит его в собственном хранилище секретов:

{
  "inputs": [
    {
      "id": "spicyapi-key",
      "type": "promptString",
      "description": "SpicyAPI key",
      "password": true
    }
  ],
  "servers": {
    "spicyapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "${input:spicyapi-key}" }
    }
  }
}

После подключения

Сразу поручите агенту настоящую работу:

Через SpicyAPI покажи доступные мне модели изображений, выбери недорогую, сгенерируй ночной кинематографичный портрет и пришли ссылку на результат.

Агент читает каталог, получает схему выбранной модели и точную стоимость, а затем останавливается и ждёт вашего подтверждения до любого списания. С установленным Skill он к тому же использует один ключ идемпотентности и читает готовые ссылки на результат вместо повторных опросов.

Процесс для production

1. Определите модель и входные данные. Выберите endpoint нужной модальности и проверьте параметры по его текущей Schema. Не угадывайте имена полей и не отбрасывайте неизвестные поля молча.
2. Создавайте один раз. Для каждой логической генерации создайте стабильный Idempotency-Key и сохраните его до первого запроса. При повторной отправке того же запроса в течение 24 часов используйте то же значение. Для новой генерации создайте новый ключ. См. Идемпотентность.
3. Сразу сохраните taskId. Это постоянный идентификатор для статуса, сверки Webhook, поддержки и биллинга. Повтор может вернуть тот же ID и не должен создавать вторую локальную запись.
4. Ожидайте с ограничением. Предпочитайте подписанный Webhook. Если нужен polling, начните примерно с 2 секунд, увеличивайте интервал в 1,5 раза, ограничьте его 15 секундами и задайте общий дедлайн. succeeded, failed, canceled и expired — конечные состояния.
5. Проверяйте callback до обработки. Проверьте X-Webhook-Timestamp, хеш исходного тела и HMAC-подпись. Удаляйте дубликаты по request_id доставки, быстро отвечайте 2xx и обрабатывайте событие в очереди. Подробности в разделе Webhooks.
6. Вовремя копируйте результат. Используйте подписанный URL из output.assets[].url напрямую и скопируйте нужные файлы в собственное хранилище. Отдельный вызов для преобразования ключа объекта в URL необязателен. URL сейчас действует 20 минут. Также изучите Медиа и Хранение данных.

POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Content-Type: application/json
Idempotency-Key: project-42-scene-07-v1

const deadline = Date.now() + 10 * 60_000;
let delay = 2_000;
while (Date.now() < deadline) {
  await sleep(delay);
  const task = await recordInfo(taskId);
  if (['succeeded', 'failed', 'canceled', 'expired'].includes(task.state)) return task;
  delay = Math.min(Math.round(delay * 1.5), 15_000);
}
throw new Error(`task ${taskId} exceeded the polling deadline`);

Локальный таймаут не доказывает сбой генерации. Сохраните taskId и выполните сверку позже. HTTP 200 также не означает успешный результат — проверяйте data.state.

Минимальная постоянная запись

Для безопасного восстановления после перезапуска храните localRequestId, idempotencyKey, taskId, model, state, lastCheckedAt, webhookDeliveryId и outputKeys. Временный URL загрузки не должен быть постоянным идентификатором файла.

Mock и приёмочные тесты

Создайте локальный контрактный mock по структурам из разделов Задачи, Webhooks и Ошибки. Обязательно проверьте:

• queued → running → succeeded и конечный сбой с code: 200, но data.state: "failed";
• повторное создание, возвращающее тот же taskId;
• верную подпись, неверную подпись и повторную доставку Webhook;
• 429, 503, сетевой таймаут и превышение общего срока polling;
• повторную выдачу истёкшего URL загрузки.

Mock проверяет оркестрацию, а не качество модели. Перед выпуском запустите небольшую реальную задачу с точно такой же моделью и структурой входных данных, как в production.

Чек-лист приёмки

• Секреты находятся только в серверном хранилище и маскируются в логах.
• Интеграция читает актуальную Schema модели, а не угадывает поля.
• У логического запроса только один сохранённый Idempotency-Key.
• taskId сохраняется до дальнейшей обработки и переживает перезапуск.
• Polling имеет backoff, максимальный интервал и общий дедлайн.
• Webhook проверяет время, исходное тело и HMAC и удаляет дубликаты доставок.
• Итог определяется по data.state, а не по HTTP-статусу или code конверта.
• Результаты копируются до истечения срока, а ключи объектов остаются постоянной ссылкой.
• Логи содержат request_id, taskId, модель и номер попытки, но не секреты и полные промпты.

В итоговом отчёте агента должны быть выбранный endpoint модели, время получения Schema, стратегия идемпотентности, дедлайн polling, схема проверки Webhook и заполненный чек-лист.