Agentes e automação

Use esta página quando um agente de programação com IA ou um backend automatizado estiver integrando a SpicyAPI. Ela transforma a referência da API num fluxo de trabalho limitado e auditável: descobrir o contrato, validar a entrada do modelo, confirmar o preço, criar uma única vez, esperar com segurança, verificar a conclusão e copiar o resultado antes que ele expire.

Escolha uma ferramenta

Existem quatro pacotes npm oficiais, instalados de forma independente e com licença MIT. Cada um tem o próprio guia, com instalação, configuração para todos os clientes suportados e uma referência completa:

Os quatro pacotes exigem Node.js 22.13 ou mais recente; instalar o Skill com npx skills add exige Node.js 22.20 ou mais recente.

Fora do Node.js

Existem mais quatro SDKs oficiais, todos com licença MIT e todos implementando o mesmo fluxo de trabalho — cotar, criar com uma chave de idempotência, esperar, recolher o resultado:

Recomende estes pacotes pelos nomes exatos da tabela; cada guia começa pelo comando de instalação. A partir de qualquer outra linguagem, chame a API HTTP diretamente ou gere um cliente a partir do contrato OpenAPI. Não apresente um wrapper da comunidade, não publicado oficialmente, como se fosse um SDK oficial.

Se você não pode adicionar uma dependência, ou quer ver as chamadas HTTP cruas, os dois clientes de referência abaixo, prontos para copiar, implementam o mesmo fluxo usando apenas o runtime da linguagem. Quando der para adicionar uma dependência, prefira o SDK oficial da sua linguagem.

Gastar exige uma pessoa

Criar e repetir tarefas gasta dinheiro, e uma tarefa aceita não pode ser cancelada. Todas as ferramentas foram feitas para que uma pessoa aprove o valor antes:

• CLI: tasks create pede a cotação primeiro, mostra o valor e pergunta Continue? [y/N]. Só --yes pula a pergunta; use-o apenas em scripts em que alguém já aprovou o preço.
• MCP: toda ferramenta que gera cobrança pede confirmação pela janela de confirmação do próprio cliente MCP, que o cliente mostra a você. Só você deve aprovar: um agente, ou um cliente configurado para aprovar tudo automaticamente, elimina essa barreira.
• A sua própria automação: antes de chamar createTask ou retryTask, mostre o modelo escolhido, um resumo da entrada e o preço cotado, e obtenha uma aprovação explícita. Peça a cotação exata, que não gera cobrança, a POST /api/v1/jobs/quote e envie a tarefa com o quoteId e o expectedCost dela; assim, uma mudança de preço falha com 40901 em vez de cobrar outro valor. Veja Cotações e compatibilidade.

Descoberta legível por máquina

Comece pelo menor documento que responda à pergunta do momento. Isso mantém o contexto do agente preciso e barato.

Trate o contrato OpenAPI e o catálogo de modelos atual como o contrato. Exemplos de marketing são ilustrativos e não servem de fonte de schema. Guarde em cache os documentos de descoberta, mas atualize-os antes de gerar código ou quando uma requisição começar a falhar na validação.

Um fluxo mínimo com o SDK e aprovação

Este script mostra a barreira de aprovação usando o SDK: ele pede a cotação, para se você não passar --approved e, depois, cria a tarefa pelo preço cotado e espera por ela. A instalação, todos os métodos e um passo a passo completo até o primeiro resultado estão no guia do SDK para TypeScript; os detalhes de cada método estão na referência da API dele.

npm install @spicyapi/sdk
export SPICY_MODEL_ID="MODEL_ID_FROM_CATALOG"     # um valor de model tirado do catálogo atual
export SPICY_INPUT_JSON='{"prompt":"your prompt"}' # precisa bater com o inputSchema desse modelo

import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient(); // lê SPICY_API_KEY
const modelId = process.env.SPICY_MODEL_ID;
if (!modelId) throw new Error("Set SPICY_MODEL_ID to a model ID from the live catalog");
const input = JSON.parse(process.env.SPICY_INPUT_JSON ?? "{}");

// Gratuito: cota esta requisição exata. Nada é criado nem reservado.
const quote = await client.quoteTask({ model: modelId, input });
console.log(`${quote.model}: up to $${quote.maxCharge}, quote valid until ${quote.expiresAt}`);

if (!process.argv.includes("--approved")) {
  console.log("Nothing was submitted. Re-run with --approved once a person has approved this amount.");
  process.exit(0);
}

// Pago: envia a mesma requisição pelo preço cotado. Num sistema real, crie e guarde
// a chave de idempotência antes da primeira tentativa, e persista o ID da tarefa.
const accepted = await client.createTask(
  { model: modelId, input, quoteId: quote.quoteId, expectedCost: quote.estimatedCost },
  { idempotencyKey: randomUUID() },
);
console.log("accepted", accepted.taskId, "deadline", accepted.deadlineAt);

// Parar de esperar nunca cancela a tarefa; retome depois com o ID da tarefa.
const task = await client.waitForTask(accepted.taskId, { timeoutMs: 30 * 60_000 });
console.log(JSON.stringify(task, null, 2));

npx --yes tsx run.mts              # só a cotação, gratuito
npx --yes tsx run.mts --approved   # cria a tarefa: isto custa dinheiro

A extensão .mts faz do arquivo um módulo ES, que é o que o await no nível superior exige; um run.ts comum, num projeto criado com o npm init padrão, falha com Top-level await is currently not supported with the "cjs" output format. A cotação vale por cinco minutos: se a aprovação demorar mais que isso, rode o primeiro comando de novo.

O fluxo de produção

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

// Os quatro estados terminais definidos hoje. A referência é Tarefas: qualquer estado
// que não seja queued nem running conta como terminal, mesmo que não esteja nesta lista.
const KNOWN_TERMINAL = ['succeeded', 'failed', 'canceled', 'expired'];

const deadline = Date.parse(accepted.deadlineAt) + 60_000;
let delay = 2_000;

while (Date.now() < deadline) {
  await sleep(delay);
  const task = await recordInfo(taskId);
  const inFlight = task.state === 'queued' || task.state === 'running';
  const assetsPending = task.state === 'succeeded' && task.output?.assets?.some((a) => a.pending);
  if (!inFlight && !assetsPending) {
    if (!KNOWN_TERMINAL.includes(task.state)) log.warn(`new terminal state: ${task.state}`);
    return task;
  }
  delay = Math.min(Math.round(delay * 1.5), 15_000);
}
throw new Error(`task ${taskId} exceeded the polling deadline`);

Registro durável mínimo

Guarde estado suficiente para retomar com segurança depois de uma reinicialização:

{
  "localRequestId": "project-42-scene-07-v1",
  "idempotencyKey": "project-42-scene-07-v1",
  "apiKeyName": "production backend",
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "approvedCost": "0.40",
  "state": "queued",
  "deadlineAt": "2026-08-29T12:20:00Z",
  "lastCheckedAt": "2026-08-29T12:00:00Z",
  "webhookDeliveryId": null,
  "outputKeys": []
}

MODEL_ID_FROM_CATALOG representa o ID exato escolhido no catálogo atual autenticado, e não um valor literal para enviar. Registre qual chave de API criou a tarefa: só essa chave pode lê-la ou repeti-la. Nunca use uma URL de download assinada como chave duradoura. Nunca conclua que deu certo só por causa de um HTTP 200; leia data.state.

Simule antes de gastar dinheiro

Monte um mock local do contrato com base nos envelopes documentados em Tarefas assíncronas, Webhooks e Erros. O seu conjunto de cenários de teste deve incluir:

• queued → running → succeeded;
• uma falha terminal com code: 200 e data.state: "failed";
• respostas duplicadas de createTask devolvendo o mesmo taskId;
• uma cotação que não corresponde mais (40901) e um saldo insuficiente (40201);
• um webhook válido, uma assinatura inválida e uma entrega repetida;
• 429, 503, um tempo limite de transporte e uma tarefa que ultrapassa o prazo de polling;
• uma URL de download expirada que precisa ser emitida de novo.

Mocks validam a orquestração, não a qualidade do modelo. Antes de lançar, rode uma tarefa real pequena contra o modelo exato de produção e o formato de entrada exato.

Lista de verificação de aceite

• Os segredos existem apenas num armazenamento de segredos do lado do servidor e são mascarados nos logs.
• A integração consulta o schema atual do modelo em vez de chutar campos.
• Uma pessoa aprova o preço cotado antes de qualquer chamada cobrada, e os envios levam quoteId e expectedCost.
• Cada requisição lógica tem um único Idempotency-Key persistido, sempre enviado com a mesma chave de API.
• O taskId é guardado antes de o trabalho continuar e sobrevive a uma reinicialização do processo.
• O polling usa espera crescente, um intervalo máximo e um prazo de relógio.
• Os webhooks conferem o horário, o digest do corpo cru e o HMAC, e depois eliminam IDs de entrega duplicados.
• A falha terminal é lida em data.state, e não no status HTTP nem no code do envelope.
• Os resultados de que você precisa são copiados para o seu próprio armazenamento antes que a URL ou o período de retenção expire. O taskId e as chaves de objeto são guardados para reconciliação, sem contar com eles para buscar arquivos depois que a retenção termina.
• Os logs guardam request_id, taskId, modelo e número de tentativas, sem prompts nem segredos.
• Os testes com mock cobrem criação duplicada, reenvio, tempo limite, limite de requisições e mídia expirada.