Agentes y automatización

Esta guía está pensada para agentes de programación con IA y backends automatizados que integran SpicyAPI. Convierte la referencia de la API en un flujo acotado, recuperable y verificable: descubrir el contrato, validar la entrada, crear una sola vez, esperar con seguridad, confirmar el estado final y guardar los resultados antes de que caduquen.

Descubrimiento legible por máquinas

Empieza por el artefacto más pequeño que resuelva la pregunta actual. Así reduces el contexto y evitas suposiciones obsoletas.

OpenAPI y el catálogo de modelos actual son el contrato. Los ejemplos comerciales son ilustrativos, no una fuente de Schema. Actualiza los documentos de descubrimiento antes de generar código o cuando aparezcan nuevos errores de validación.

Integraciones npm oficiales

SDK, CLI, MCP y el Agent Skill portátil son cuatro paquetes npm MIT independientes. Instala solo las herramientas que necesites. @spicyapi/skill sigue el formato portátil Agent Skills y no está limitado a 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

El Skill se instala en ~/.agents/skills/spicyapi de forma predeterminada. Si un Agent usa otro directorio Skills, indica el destino exacto con --target /ruta/exacta/spicyapi.

Usarlo dentro de un agente de código

El servidor MCP se ejecuta en local por stdio y entrega al agente el catálogo de modelos, los presupuestos, la creación de tareas y la recogida de resultados. Toda acción facturable se detiene en una confirmación que el agente no puede saltarse. Abajo está la forma que recomienda hoy cada cliente; la ubicación y el formato de la configuración los define el cliente y cambian entre versiones, así que su documentación es la referencia.

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

Ambos comandos copian SPICY_API_KEY de tu shell actual a la configuración local de ese cliente, así que ejecútalos en una terminal donde la clave ya esté exportada. Se queda en tu máquina: nunca la subas al repositorio.

Cursor, Windsurf y Gemini CLI

Sus archivos de configuración son ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json y ~/.gemini/settings.json, con la misma forma:

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

Son archivos de usuario fuera de tu repositorio. Cuando YOUR_SERVER_SIDE_KEY tenga una clave real, no copies este bloque a ningún archivo del proyecto que se versione.

VS Code

.vscode/mcp.json se versiona con tu repositorio, así que la clave no puede vivir dentro. Deja que VS Code pida el valor la primera vez que arranca el servidor y lo guarde en su propio almacén de secretos:

{
  "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}" }
    }
  }
}

Una vez conectado

Pídele al agente algo real:

Con SpicyAPI, lista los modelos de imagen que puedo llamar, elige uno barato, genera un retrato nocturno cinematográfico y dame el enlace del resultado cuando termine.

El agente lee el catálogo, obtiene el esquema de ese modelo y un presupuesto exacto, y se detiene para que confirmes antes de cobrar nada. Con el Skill instalado, además mantiene una sola clave de idempotencia y lee los enlaces de resultado ya listos en lugar de sondear repetidamente.

Flujo de producción

1. Resuelve el modelo y la entrada. Elige el endpoint de la modalidad correcta y valida contra su Schema actual. No adivines campos ni descartes silenciosamente los desconocidos.
2. Crea una sola vez. Genera un Idempotency-Key estable para cada generación lógica y guárdalo antes de la primera llamada. Reutilízalo al reenviar la misma solicitud durante su vigencia de 24 horas; una generación nueva necesita otra clave. Consulta Idempotencia.
3. Guarda taskId de inmediato. Es la identidad duradera para consultar estado, conciliar Webhooks, soporte y facturación. Un reintento puede devolver el mismo ID y no debe crear un segundo registro local.
4. Espera con un límite. Prioriza un Webhook firmado. Si necesitas polling, empieza cerca de 2 segundos, multiplica por 1,5, limita el intervalo a 15 segundos y fija además un plazo total. succeeded, failed, canceled y expired son estados terminales.
5. Verifica el callback antes de actuar. Comprueba X-Webhook-Timestamp, el hash del cuerpo sin transformar y la firma HMAC. Deduplica con el request_id de entrega, responde rápido con 2xx y procesa después en una cola. Consulta Webhooks.
6. Copia el resultado a tiempo. Usa las URL de resultado incluidas en la respuesta de estado o en el webhook y copia los archivos que quieras conservar a tu propio almacenamiento. Si utilizas una URL firmada, respeta su vencimiento; no es necesario solicitar otra URL para cada resultado. Revisa también Multimedia y Retención.

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`);

Un timeout local no demuestra que la generación haya fallado. Conserva taskId y concilia el estado más tarde. Tampoco interpretes HTTP 200 como éxito del contenido: lee data.state.

Registro duradero mínimo

Guarda localRequestId, idempotencyKey, taskId, model, state, lastCheckedAt, webhookDeliveryId y outputKeys para poder continuar después de un reinicio. Una URL de descarga temporal nunca debe ser el identificador permanente del archivo.

Mock y pruebas de aceptación

Crea un mock contractual local con las envolturas documentadas en Tareas, Webhooks y Errores. Debe cubrir como mínimo:

• queued → running → succeeded y un fallo terminal con code: 200 y data.state: "failed";
• creación duplicada que devuelve el mismo taskId;
• firma válida, firma inválida y reenvío del mismo Webhook;
• 429, 503, timeout de transporte y vencimiento del plazo de polling;
• reemisión de una URL de descarga caducada.

El mock valida la orquestación, no la calidad del modelo. Antes del lanzamiento ejecuta una tarea real pequeña con el mismo modelo y estructura de entrada de producción.

Lista de aceptación

• Los secretos solo viven en el almacén del servidor y se ocultan en los logs.
• La integración lee el Schema actual del modelo en vez de inventar campos.
• Cada solicitud lógica tiene un único Idempotency-Key persistido.
• taskId se guarda antes de continuar y sobrevive a un reinicio.
• El polling tiene backoff, intervalo máximo y plazo total.
• Los Webhooks verifican tiempo, cuerpo original y HMAC, y deduplican entregas.
• El resultado final se lee de data.state, no del estado HTTP ni de code.
• Los resultados se copian antes de caducar; las claves de objeto son la referencia duradera.
• Los logs incluyen request_id, taskId, modelo e intento, pero no secretos ni prompts completos.

El informe final del agente debe incluir endpoint elegido, hora de lectura del Schema, estrategia de idempotencia, plazo de polling, verificación de Webhook y esta lista completada.