Agentes e automação

Este guia é para agentes de programação com IA e backends automatizados que integram a SpicyAPI. Ele transforma a referência da API em um fluxo limitado, retomável e verificável: descobrir o contrato, validar a entrada, criar uma única vez, aguardar com segurança, confirmar o estado final e salvar os resultados antes do vencimento.

Descoberta legível por máquina

Comece pelo menor artefato capaz de responder à pergunta atual. Isso reduz o contexto e evita suposições desatualizadas.

O OpenAPI e o catálogo de modelos atualizado formam o contrato. Exemplos de marketing são ilustrativos, não uma fonte de Schema. Atualize os arquivos de descoberta antes de gerar código ou quando surgir um novo erro de validação.

Integrações npm oficiais

SDK, CLI, MCP e o Agent Skill portátil são quatro pacotes npm MIT independentes. Instale apenas as ferramentas necessárias. @spicyapi/skill segue o formato portátil Agent Skills e não é limitado ao 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

O Skill é instalado em ~/.agents/skills/spicyapi por padrão. Para um Agent que use outro diretório Skills, informe o destino exato com --target /caminho/exato/spicyapi.

Usar dentro de um agente de código

O servidor MCP roda localmente por stdio e entrega ao agente o catálogo de modelos, os orçamentos, a criação de tarefas e a leitura dos resultados. Toda ação cobrada para em uma confirmação que o agente não consegue pular. Abaixo está a forma que cada cliente recomenda hoje; o local e o formato da configuração são definidos pelo cliente e mudam entre versões, então a documentação deles é a referência.

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

Os dois comandos copiam SPICY_API_KEY do seu shell atual para a configuração local do cliente, então rode em um terminal onde a chave já esteja exportada. Ela fica na sua máquina — nunca versione.

Cursor, Windsurf e Gemini CLI

Os arquivos de configuração são ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json e ~/.gemini/settings.json, com o mesmo formato:

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

São arquivos de usuário, fora do seu repositório. Depois que YOUR_SERVER_SIDE_KEY virar uma chave real, nunca copie esse bloco para um arquivo de projeto versionado.

VS Code

.vscode/mcp.json é versionado junto com o repositório, então a chave não pode ficar nele. Deixe o VS Code pedir o valor na primeira vez que o servidor sobe e guardar no cofre dele:

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

Depois de conectar

Peça algo de verdade ao agente:

Use a SpicyAPI para listar os modelos de imagem que eu posso chamar, escolha um barato, gere um retrato noturno cinematográfico e me mande o link do resultado quando terminar.

O agente lê o catálogo, busca o schema daquele modelo e obtém um orçamento exato, e então para para você confirmar antes de qualquer cobrança. Com o Skill instalado, ele também mantém uma única chave de idempotência e lê os links de resultado prontos em vez de ficar consultando.

Fluxo de produção

1. Resolva o modelo e a entrada. Escolha o endpoint da modalidade desejada e valide a entrada com o Schema atual. Não adivinhe campos nem descarte silenciosamente os desconhecidos.
2. Crie uma única vez. Gere um Idempotency-Key estável para cada geração lógica e persista antes da primeira chamada. Reutilize o mesmo valor ao reenviar a mesma requisição durante a validade de 24 horas; uma geração nova precisa de outra chave. Consulte Idempotência.
3. Salve taskId imediatamente. Essa é a identidade durável para status, conciliação de Webhook, suporte e cobrança. Uma nova tentativa pode devolver o mesmo ID e não deve criar outro registro local.
4. Aguarde com limite. Prefira um Webhook assinado. Se precisar consultar, comece por volta de 2 segundos, multiplique por 1,5, limite o intervalo a 15 segundos e defina também um prazo total. succeeded, failed, canceled e expired são estados terminais.
5. Verifique o callback antes de agir. Valide X-Webhook-Timestamp, o hash do corpo bruto e a assinatura HMAC. Elimine duplicatas pelo request_id da entrega, responda rapidamente com 2xx e processe depois em uma fila. Consulte Webhooks.
6. Copie a saída a tempo. Use as URLs de resultado incluídas na resposta de status ou no webhook e copie os arquivos que deseja conservar para seu próprio armazenamento. Se usar uma URL assinada, respeite o vencimento; não é necessário solicitar outra URL para cada resultado. Veja também Mídia e Retenção.

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

Um timeout local não prova que a geração falhou. Guarde taskId e concilie o estado depois. HTTP 200 também não significa sucesso da mídia: leia data.state.

Registro durável mínimo

Salve localRequestId, idempotencyKey, taskId, model, state, lastCheckedAt, webhookDeliveryId e outputKeys para retomar com segurança depois de uma reinicialização. Uma URL temporária nunca deve ser o identificador permanente do arquivo.

Mock e testes de aceitação

Monte um mock contratual local com os envelopes de Tarefas, Webhooks e Erros. Inclua pelo menos:

• queued → running → succeeded e uma falha terminal com code: 200 e data.state: "failed";
• criação duplicada que retorna o mesmo taskId;
• assinatura válida, assinatura inválida e reentrega do mesmo Webhook;
• 429, 503, timeout de transporte e vencimento do prazo de consulta;
• nova emissão de uma URL de download vencida.

O mock valida a orquestração, não a qualidade do modelo. Antes do lançamento, rode uma tarefa real pequena com o mesmo modelo e formato de entrada da produção.

Checklist de aceitação

• Segredos ficam apenas no cofre do servidor e são ocultados nos logs.
• A integração lê o Schema atual do modelo em vez de inventar campos.
• Cada solicitação lógica possui um único Idempotency-Key persistido.
• taskId é salvo antes do restante do processamento e sobrevive a reinicializações.
• A consulta tem backoff, intervalo máximo e prazo total.
• Webhooks verificam horário, corpo bruto e HMAC e eliminam entregas duplicadas.
• O estado final vem de data.state, não do HTTP nem do code do envelope.
• Resultados são copiados antes do vencimento; chaves de objeto são a referência durável.
• Logs guardam request_id, taskId, modelo e tentativa, mas não segredos nem prompts completos.

O relatório final do agente deve incluir endpoint escolhido, horário de leitura do Schema, estratégia de idempotência, prazo de consulta, verificação de Webhook e esta checklist preenchida.