Como a SpicyAPI funciona

Se você está chegando agora, comece por aqui. Esta página explica em palavras simples o que a SpicyAPI faz, ajuda você a escolher o jeito de usar que combina com você e apresenta as poucas ideias que o resto desta documentação dá como conhecidas. Não é preciso saber programar para ler.

O que é a SpicyAPI

A SpicyAPI dá a você uma única chave de API para modelos de imagem, vídeo e texto de vários fabricantes diferentes, e cobra por uso, em dólares americanos.

Sem ela, usar vários modelos de IA significa abrir conta em cada empresa, aprender o formato de requisição de cada uma e colocar saldo em cada uma separadamente. Com a SpicyAPI você tem uma conta e um saldo. Você escolhe um modelo, envia seu prompt (e uma imagem de referência, se o modelo aceitar) e recebe de volta uma imagem, um vídeo ou um texto. Trocar de modelo não muda a forma de enviar a requisição nem de buscar o resultado.

• Uma chave, muitos modelos. Todos os modelos de imagem e vídeo funcionam do mesmo jeito: você envia uma tarefa e depois busca o resultado. Os modelos de texto também aceitam os formatos de requisição das bibliotecas oficiais da OpenAI, da Anthropic e do Google Gemini.
• Pague pelo uso, em dólares. Dependendo do modelo, o preço é por imagem, por segundo de vídeo, por requisição ou por token. Não há assinatura nem sistema de créditos ou pontos: o preço que você vê é o valor em dólares que sai do seu saldo. Também não há plano gratuito, então você adiciona saldo antes da primeira geração. Veja Cobrança.
• Quando uma tarefa é aceita, o custo estimado fica reservado no seu saldo. Se ela der certo, você paga pelo que foi realmente usado, nunca mais do que esse valor. Tarefas que falham ou expiram normalmente liberam toda a reserva. Algumas recusas de conteúdo são cobradas pelo orçamento aceito, somente quando a página do modelo informa explicitamente essa exceção. Confira settled e cost para saber o valor final.
• Nenhum modo de conteúdo para configurar. A SpicyAPI não exige nenhum parâmetro de modo de conteúdo na requisição e não faz revisão de conteúdo requisição por requisição. O que um modelo aceita gerar depende do próprio modelo: alguns recusam ou suavizam certos pedidos. A responsabilidade pelo uso do que você gera continua sendo sua; veja Responsabilidade sobre conteúdo e uso.

A SpicyAPI não atende a China continental, e algumas outras regiões também têm restrições; veja a mesma página de política.

O que dá para criar

O catálogo também traz algumas tarefas de vídeo mais especializadas, como fazer um personagem se mover com o movimento de outro clipe ou estender um clipe existente. Modelos entram e saem do catálogo com o tempo, então é sempre o catálogo atual que diz o que existe hoje.

Para ver os modelos atuais com imagens, descrições e preços, abra spicyapi.ai/explore. A mesma lista está disponível sem conta e sem chave em JSON puro, se você quiser olhar pelo terminal:

curl "https://api.spicyapi.ai/console/v1/catalog/models?locale=en&strict=1"

O comando imprime um bloco de texto bem longo. Cada modelo ali tem uma modality (image, video ou text), suas tasks e um price inicial. Essa lista pública serve para explorar; depois que você tiver uma chave, a lista do que a sua chave realmente pode chamar vem de GET /api/v1/models. Veja Catálogo no glossário.

Escolha seu caminho

Há cinco jeitos de começar. Todos compartilham a mesma conta, o mesmo saldo, os mesmos modelos e os mesmos preços, então você pode começar por um e somar outro depois.

Testar no navegador

• Ideal para: quem quer ver o que um modelo faz antes de decidir qualquer coisa. Nada para instalar, nenhum código.
• Você precisa de: um navegador. Dá para abrir qualquer modelo e preencher o formulário dele sem conta. Para apertar Executar, você precisa entrar na conta e ter saldo.
• Custa dinheiro? Cada execução é cobrada como uma chamada de API. Tarefas que falham ou expiram normalmente liberam toda a reserva. Algumas recusas de conteúdo são cobradas pelo orçamento aceito, somente quando a página do modelo informa explicitamente essa exceção. Confira settled e cost para saber o valor final.
• Comece assim: abra spicyapi.ai/explore, escolha um modelo e use a aba Playground na página dele. As execuções concluídas também aparecem em Registros no console.

Pedir ao seu assistente de IA

• Ideal para: quem já usa um assistente de IA como Claude, Cursor, VS Code, Codex, Windsurf ou Gemini CLI e quer explorar modelos, comparar preços e gerar imagens ou vídeos conversando. Desenvolvedores também usam esse caminho para explorar antes de construir.
• Você precisa de: Node.js 22.13 ou mais recente, uma chave de API e um aplicativo de assistente com suporte a MCP. As etapas pagas só funcionam em aplicativos capazes de mostrar uma pergunta de confirmação para você.
• Custa dinheiro? Explorar, cotar e consultar resultados é grátis. Iniciar ou repetir uma geração primeiro pausa tudo e mostra o preço numa pergunta para você; o assistente não pode responder essa pergunta por você.
• Comece assim: o servidor MCP dá ao assistente ações da SpicyAPI. O Agent Skill ensina um assistente de programação com IA a escrever integrações com a SpicyAPI do jeito seguro, e funciona bem junto com ele.

Digitar comandos no terminal

• Ideal para: comparar preços, gerar imagens e vídeos no seu próprio computador e salvar os arquivos, repetir o mesmo tipo de trabalho ou rodar um script simples. Sem programar.
• Você precisa de: um terminal, Node.js 22.13 ou mais recente e uma chave de API guardada na variável de ambiente SPICY_API_KEY.
• Custa dinheiro? Só spicyapi tasks create e spicyapi tasks retry podem gerar cobrança, e os dois perguntam antes de cobrar qualquer coisa.
• Comece assim: Ferramenta de linha de comando (CLI).

Montar workflows de nodes no ComfyUI

• Ideal para: quem já trabalha no ComfyUI e quer modelos hospedados ao lado dos nodes locais: encadear um modelo de imagem num modelo de vídeo, acrescentar uma trilha sonora ou deixar um modelo de conversa escrever o prompt.
• Você precisa de: o ComfyUI no seu computador ou num servidor e uma chave de API. Os modelos da SpicyAPI rodam nos nossos servidores, então não é preciso GPU para eles.
• Custa dinheiro? Cada execução é cobrada como uma chamada de API. Todo node mostra a tarifa, cota antes de rodar e pode interromper qualquer execução acima de um limite que você define.
• Comece assim: Nodes do ComfyUI.

Escrever código

• Ideal para: colocar geração de imagem, vídeo ou texto dentro do seu próprio aplicativo, do backend do seu site ou de um pipeline de dados.
• Você precisa de: código que rode num servidor ou no seu próprio computador, porque uma chave de API nunca pode ficar numa página da web nem num aplicativo de celular. Há SDKs oficiais para TypeScript (Node.js 22.13 ou mais recente), Python 3.11+, Go 1.23+, PHP 8.1+ e Java 17+; qualquer outra linguagem pode chamar a API HTTP diretamente.
• Custa dinheiro? Toda geração aceita é cobrada. Cotações, leituras do catálogo e consultas de tarefas são grátis.
• Comece assim: o SDK para TypeScript para Node.js, ou os SDKs para Python, Go, PHP e Java. Para HTTP puro, com exemplos em curl, Node.js, Python e Go, use o Início rápido; veja Texto e streaming para modelos de conversa e o tutorial de imagem para vídeo para um exemplo completo, do começo ao fim.

Ideias que aparecem em todo lugar

Nada disto é necessário para testar o Playground, mas todas as outras páginas partem do princípio de que você conhece estas ideias. Cada uma ganha aqui uma ou duas frases, um link para a página que traz os detalhes e um verbete mais longo, em linguagem simples, no glossário.

O que acontece quando você gera algo

1. Você escolhe um modelo e preenche as entradas dele.
2. Se quiser, pede uma cotação: o preço exato, de graça.
3. Você envia. A SpicyAPI aceita a requisição como uma tarefa, devolve um ID da tarefa e reserva o custo estimado no seu saldo.
4. O modelo trabalha em segundo plano. Imagens costumam levar segundos; vídeos muitas vezes levam minutos.
5. A tarefa termina. Se deu certo, você paga pelo que foi realmente usado, nunca mais do que o valor reservado. Tarefas que falham ou expiram normalmente liberam toda a reserva. Algumas recusas de conteúdo são cobradas pelo orçamento aceito, somente quando a página do modelo informa explicitamente essa exceção. Confira settled e cost para saber o valor final.
6. Você busca o resultado, seja porque a SpicyAPI chama o seu servidor de volta, seja porque você pergunta, e baixa o arquivo. Os links de download são temporários e os arquivos ficam guardados por tempo limitado, então salve o que quiser manter.

ID do modelo

Todo modelo tem um ID exato no formato publisher/model/task. Copie o ID do catálogo atual (GET /api/v1/models, spicyapi models list ou listModels()), e não da memória ou de uma página da web: modelos são adicionados, pausados e retirados. Nos exemplos de código desta documentação aparece MODEL_ID_FROM_CATALOG onde deve entrar um ID real. Catálogo de modelos e schemas · Glossário: ID do modelo

Tarefas e seus estados

A geração de imagens e vídeos é assíncrona: enviar e buscar o resultado são dois passos separados, ligados por um ID da tarefa que começa com job_. Uma tarefa passa de queued para running e termina como succeeded, failed ou expired; qualquer estado que não seja queued nem running é final. Já os modelos de texto respondem na mesma conexão, muitas vezes palavra por palavra. Tarefas assíncronas · Texto e streaming · Glossário: estado da tarefa

Cotação

Uma cotação calcula o preço da sua requisição exata sem iniciar nada e sem reservar dinheiro. Ela vale por cinco minutos. Se você enviar usando a cotação e, nesse meio-tempo, o preço ou a requisição tiver mudado, o envio é recusado em vez de ser cobrado por outro valor. Cotações e compatibilidade · Glossário: cotação

Chave de idempotência

Um rótulo que você escolhe para um trabalho e envia junto com ele. Se a sua conexão cair e você mandar a mesma requisição de novo, com o mesmo rótulo e a mesma chave de API, dentro de 24 horas, você recebe de volta a tarefa original em vez de iniciar e pagar uma segunda. A CLI e o servidor MCP criam esse rótulo para você; com o SDK ou com HTTP puro, você envia o seu. Idempotência · Glossário: chave de idempotência

Callbacks

Em vez de perguntar várias vezes se uma tarefa já terminou, você pode dar a ela um callBackUrl: um endereço HTTPS público no seu servidor. Quando a tarefa termina, a SpicyAPI envia o resultado para lá, com uma assinatura que permite conferir que ele veio mesmo da SpicyAPI. Perguntar repetidamente, o chamado polling, não tem problema enquanto você testa no seu próprio computador. Webhooks · Glossário: webhook

Por quanto tempo os resultados ficam guardados

O link de download de um resultado dura cerca de 20 minutos; consulte a tarefa de novo para receber um link novo. Os arquivos gerados ficam guardados por no máximo cerca de 14 dias, os arquivos enviados por um dia e o texto do prompt por 30 dias, e você pode encurtar os três prazos ou destruir o conteúdo de uma tarefa quando quiser. Os registros de cobrança são mantidos por muito mais tempo. Baixe tudo o que quiser guardar. Retenção e destruição · Glossário: retenção

Saldo e limites de gasto

Seu saldo é em dólares americanos, pré-pago. Cada chave de API também pode ter um limite de gasto diário, mensal e acumulado, definido por você. Quando o seu saldo não cobre uma tarefa, você recebe o erro 40201; quando um limite é atingido, recebe 40202. Nenhum dos dois cria tarefa nem cobra nada. Cobrança · Autenticação · Glossário: limite de gasto

Sua primeira vez, passo a passo

Onde conseguir ajuda

• Respostas rápidas: Perguntas frequentes, Glossário, Solução de problemas e recuperação e Erros.
• O serviço está no ar? status.spicyapi.ai.
• Fale com a gente: abra uma conversa na página Suporte do console ou use a página de contato. Informe o request_id ou o ID da tarefa e o horário em UTC. Nunca envie sua chave de API.

Próximos passos