Cotações e compatibilidade de protocolos

Cotar uma requisição exata

Uma cotação informa o preço de uma requisição exata antes de você pagar. Ela é gratuita, não cria tarefa nenhuma e não reserva dinheiro. Depois, você envia a mesma requisição com a cotação anexada, e ela só é aceita pelo preço que foi mostrado a você.

Os comandos abaixo são para um terminal de macOS ou Linux, com SPICY_API_KEY definida como no Início rápido. MODEL_ID_FROM_CATALOG é um marcador: use um valor de model do seu catálogo atual (GET /api/v1/models) e tire cada campo de input do schema desse modelo.

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" }
}

curl https://api.spicyapi.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "QUOTE_ID_FROM_RESPONSE",
    "model": "MODEL_ID_FROM_CATALOG",
    "estimatedCost": "0.008",
    "maxCharge": "0.008",
    "currency": "USD",
    "quantity": "1",
    "unit": "per_image",
    "expiresAt": "2026-09-17T10:05:00Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

{
  "model": "MODEL_ID_FROM_CATALOG",
  "input": { "prompt": "A cinematic night portrait" },
  "quoteId": "QUOTE_ID_FROM_RESPONSE",
  "expectedCost": "0.008"
}

SPICY_IDEMPOTENCY_KEY="$(uuidgen)"   # uma vez por tarefa nova; reaproveite só para reenviar esta mesma requisição

curl https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  --data-binary @submit.json

POST /api/v1/jobs/stream, o stream de texto nativo, aceita cotação do mesmo jeito; veja Texto e streaming.

Recuperar-se de uma resposta perdida

Se um envio estourou o tempo limite ou a conexão caiu, você não sabe se ele foi aceito. Para createTask, retry e POST /v1/videos:

1. Reenvie a requisição original com o Idempotency-Key original, usando a mesma chave de API. Você recebe de volta a tarefa original, no estado em que ela estiver agora, e não é cobrado duas vezes.
2. Não crie outra tarefa com uma chave nova. Chave nova significa geração nova e cobrança nova.
3. Repetir uma requisição já aceita continua valendo depois que a cotação expira. A expiração barra a aceitação, não a tarefa que a aceitação já criou.
4. Um 409 não quer dizer "não foi criada". Ou a requisição mudou (é um trabalho novo, que precisa de chave nova), ou ela foi enviada com outra chave de API da mesma conta (reenvie com a chave original). Veja Idempotência.
5. Leia cost e settled em recordInfo para saber a cobrança final.

Cotações nas ferramentas oficiais

A CLI e o servidor MCP pedem a cotação e perguntam a uma pessoa antes de toda chamada cobrada, então você não precisa construir essa etapa por conta própria:

• CLI: spicyapi tasks quote informa o preço de uma requisição; spicyapi tasks create pede a cotação de novo, mostra o valor e pergunta antes de criar. Veja Custos, confirmação e segurança.
• MCP: o assistente pode pedir cotações à vontade, mas criar uma tarefa faz o seu cliente de IA perguntar a você, com o preço. Veja Custos, confirmação e segurança.
• SDK: quoteTask retorna a cotação; passe o quoteId e o estimatedCost dela para createTask ou run.

Compatibilidade de texto e vídeo

A SpicyAPI também fala os formatos da OpenAI, da Anthropic e do Google Gemini para modelos de texto, e o formato OpenAI Videos para vídeo. A lista completa de endpoints está na referência da API; requisições, streams e erros de cada protocolo estão em Texto e streaming.

URL base. O formato da OpenAI usa https://api.spicyapi.ai/v1. Os SDKs da Anthropic e do Google GenAI acrescentam /v1 ou /v1beta sozinhos, então, para eles, defina a URL base como https://api.spicyapi.ai.

Credencial. Uma só chave de API para todos, no cabeçalho Authorization: Bearer. O cabeçalho x-api-key, usado pelo SDK da Anthropic, e o x-goog-api-key, usado pelo SDK do Google GenAI, também são aceitos. Um ?key= na URL nunca é.

Modelo. Escolha um modelo exato do catálogo atual. Se ferramentas, mensagens com imagem e opções de geração funcionam depende do schema desse modelo, não do protocolo que você escolheu.

Formato da resposta. Cada protocolo retorna o próprio envelope, e não o envelope {code, msg, data, request_id} da plataforma.

Campos de raciocínio

Modelos de chat que expõem o texto do raciocínio podem retornar uma string opcional em message.reasoning_content, ou em delta.reasoning_content durante o streaming. Ao continuar depois de uma chamada de ferramenta, você pode preservá-la na mensagem de assistente correspondente, quando o schema atual do modelo permitir.

usage.completion_tokens_details.reasoning_tokens descreve a parte de raciocínio já incluída em completion_tokens; não a some de novo. Nem todo modelo retorna texto de raciocínio ou esse detalhamento de tokens.

Dois formatos que vale conhecer antes de construir

• Responses exige a conversa inteira em input. previous_response_id não é suportado.
• Videos aceita JSON com model, prompt, input_reference, seconds e size, que são convertidos para os campos próprios do modelo. O id de vídeo retornado também é um ID de tarefa aceito por recordInfo. O endpoint de conteúdo dele redireciona com HTTP 302 para uma URL assinada de curta duração.

Para um exemplo de chat com streaming usando os clientes oficiais da OpenAI, da Anthropic e do Google, veja Use um SDK oficial. A CLI e o servidor MCP enviam e acompanham tarefas nativas; eles não transmitem tokens de chat.