Cotações e compatibilidade

Salve a solicitação completa em request.json conforme o schema atual do modelo: model, input e callBackUrl opcional. A cotação não cria tarefas nem reserva saldo. Ela vincula a identidade, o modelo e a solicitação por cinco minutos.

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

estimatedCost, maxCharge e quantity são strings decimais; currency é USD. Mostre o valor, o limite e expiresAt. Após a confirmação, envie a mesma solicitação com quoteId e expectedCost. Mudanças de entrada, vencimento ou preço retornam 40901 em uma nova aceitação; faça outra cotação e peça nova confirmação.

Se a resposta se perder, reutilize o Idempotency-Key original. Não crie outra tarefa com uma chave nova. Uma solicitação já aceita pode ser repetida após o vencimento da cotação. Confira o valor final em cost e settled de recordInfo; estimativa ou marcador de fim do texto não comprovam a liquidação.

SDK, CLI e MCP

CLI tasks create cota antes de confirmar; execução não interativa exige --yes explícito. MCP spicyapi_task_quote apenas cota. spicyapi_task_create vincula a cotação ao estado assinado e pede confirmação ao usuário pelo protocolo. O agente não pode confirmar por ele.

spicyapi tasks quote --model "$SPICY_MODEL" --input-file input.json
spicyapi tasks create --model "$SPICY_MODEL" --input-file input.json \
  --idempotency-key "$SPICY_IDEMPOTENCY_KEY" --wait

Compatibilidade de texto e vídeo

A URL base do formato OpenAI é https://api.spicyapi.ai/v1. Nos SDKs da Anthropic e do Google GenAI, use https://api.spicyapi.ai como URL base; eles acrescentam /v1 ou /v1beta por conta própria. Todas as APIs compatíveis usam a mesma chave de API, enviada no cabeçalho Authorization: Bearer; também são aceitos x-api-key, usado pelo SDK da Anthropic, e x-goog-api-key, usado pelo SDK do Google GenAI. ?key= na URL não é aceito. Escolha no catálogo atual um modelo exato que suporte chat; chamadas de ferramentas, mensagens com imagens e parâmetros de geração dependem do schema do modelo. As respostas seguem o protocolo correspondente, sem o envelope JSON da plataforma. O mapeamento de parâmetros de cada protocolo, a forma como cada fluxo termina e o formato dos erros estão em Texto e streaming.

Modelos Chat que expõem texto de raciocínio podem retornar a string opcional message.reasoning_content, ou delta.reasoning_content em streaming. Ao continuar após uma chamada de ferramenta, você pode preservá-la na mensagem assistant correspondente, conforme o suporte no esquema atual do modelo. usage.completion_tokens_details.reasoning_tokens já está incluído em completion_tokens; não some esse valor novamente. Nem todos os modelos retornam raciocínio ou detalhes de tokens.

Responses exige a conversa completa em input; previous_response_id não é suportado. Videos aceita JSON com model, prompt, input_reference, seconds e size. O endpoint content redireciona com HTTP 302 para uma URL assinada temporária. Consulte os campos e estados completos no OpenAPI.

quoteId e expectedCost se aplicam a jobs/createTask e jobs/stream. As APIs compatíveis /v1 e /v1beta usam o preço na aceitação. Use a API nativa de tarefas quando precisar confirmar um limite de cobrança.

OpenAPI · API

Streaming com o cliente oficial da OpenAI

Para Chat Completions, use diretamente o cliente oficial openai. O @spicyapi/sdk cuida de tarefas nativas, cotações e uploads. Instale openai separadamente e execute o exemplo no seu servidor, com o ID exato de um modelo de chat disponível e uma chave de idempotência persistente por ação do usuário.

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SPICY_API_KEY,
  baseURL: "https://api.spicyapi.ai/v1",
  maxRetries: 0,
});
const signal = AbortSignal.timeout(120_000);
const stream = await client.chat.completions.create({
  model: process.env.SPICY_MODEL,
  messages: [{ role: "user", content: "Explain a rainbow in one sentence." }],
  stream: true,
  stream_options: { include_usage: true },
}, {
  signal,
  headers: { "Idempotency-Key": process.env.SPICY_IDEMPOTENCY_KEY },
});
try {
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta.content ?? "");
    if (chunk.usage) process.stderr.write(JSON.stringify(chunk.usage) + "\n");
  }
} finally {
  stream.controller.abort();
}

O sinal de interrupção cobre a conexão e toda a leitura do fluxo. Interromper encerra a recepção local; não cancela uma tarefa aceita nem garante reembolso. Sem streaming, use stream: false e leia choices[0].message.content. Junte os fragmentos de chamadas de ferramentas por index, preserve a mensagem assistant completa e adicione os resultados com o tool_call_id correspondente. Use ferramentas e campos de raciocínio apenas se o schema do modelo permitir.

CLI e MCP enviam e acompanham tarefas nativas, sem streaming de tokens de chat. Use este cliente em interfaces ao vivo ou jobs/stream quando precisar confirmar uma cotação.