Ferramenta de linha de comando (CLI)

O que é a CLI

spicyapi é um pequeno programa que você roda num terminal, a janela em que você digita comandos em vez de clicar em botões. Cada comando faz uma coisa só: listar os modelos que a sua conta pode usar, dizer quanto uma geração vai custar, iniciar a geração de uma imagem ou de um vídeo, esperar que ela termine e entregar um link para baixar o resultado.

Você não escreve código nenhum. Digita um comando, aperta Enter e lê a resposta.

Ela é uma boa escolha quando você quer:

• testar modelos e comparar preços antes que alguém escreva uma integração;
• gerar imagens ou vídeos a partir do seu próprio computador e salvar os arquivos;
• repetir o mesmo tipo de geração sem precisar clicar numa página toda vez;
• conferir as configurações exatas de um modelo antes de construir algo em cima dele.

A CLI cobre geração de imagem e de vídeo. Modelos de texto e de conversa são chamados pelos endpoints compatíveis com chat descritos em Texto e streaming.

Existem outras três ferramentas oficiais. Escolha a CLI se você quer digitar os comandos por conta própria:

Escrevendo em outra linguagem? Também existem SDKs oficiais para Python, Go, PHP e Java.

O que você pode fazer

Nos comandos acima, uma palavra entre os sinais de menor e maior, como <task-id>, quer dizer "coloque aqui o seu próprio valor", sem os sinais.

Antes de começar

Você precisa de quatro coisas: um terminal, o Node.js, uma chave de API e um jeito de rodar a CLI. Na primeira vez, isso leva uns dez minutos.

node -v

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Seu primeiro resultado

Este passo a passo gera uma imagem e faz o download dela. Cada passo mostra o comando, mais ou menos o que você vai ver e o que acabou de acontecer. Os seus números, IDs e horários vão ser diferentes.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

Como ler a saída

• A saída normal mostra um name: value por linha. Valores com várias partes, como output ou retention, são impressos como JSON numa única linha.
• --json imprime a resposta completa como JSON indentado. Funciona com todos os comandos, antes ou depois do nome do comando: spicyapi --json balance e spicyapi balance --json dão no mesmo.
• Os resultados vão para a saída normal da tela; as mensagens vão para a saída de erros. Os preços, a chave de idempotência, as linhas Accepted: e os erros são mensagens. Por isso, spicyapi --json tasks get <task-id> > task.json salva só o resultado em task.json, enquanto as mensagens continuam aparecendo na tela.
• Os erros têm a forma Error: <what went wrong> (request req_…), normalmente seguidos de uma linha Next: que diz o que fazer. Com --json, um erro é um objeto JSON de uma linha com error, type, status, code e requestId, sem linha Next:. Quando nenhuma chave está definida, type é MissingApiKeyError. Informe o valor req_… se falar com o suporte.
• Dinheiro é um valor em dólares americanos escrito como texto simples, sem o sinal $, como 0.03.
• Horários estão em UTC. O Z no final de 2026-09-17T08:05:00Z significa UTC.
• O código de saída é 0 quando um comando dá certo e diferente de 0 quando ele falha, o que os scripts podem conferir.

Referência de comandos

Todo comando também tem ajuda embutida: acrescente --help, por exemplo spicyapi tasks create --help.

Opções globais e variáveis de ambiente

Estas opções funcionam com todos os comandos.

status

O que faz: confere se a SpicyAPI está no ar e acessível a partir do seu computador.

spicyapi status

Sem opções. Não precisa de chave. Gratuito.

Saída: uma frase. SpicyAPI is reachable — … answered in … ms. quer dizer que está tudo certo. could not be reached quer dizer que o seu computador não recebeu resposta: confira a sua rede ou o seu proxy. is not healthy ou reports it is not ready indica um problema do nosso lado; os incidentes em andamento aparecem em status.spicyapi.ai.

Com --json, você vê as verificações brutas. operational: true é a resposta que importa; um item readiness com status 404 é normal no endereço público.

docs search

O que faz: encontra a página da documentação sobre um assunto. Ele pesquisa num pequeno índice embutido na CLI, então funciona sem chave e sem chamar a SpicyAPI. Cada resultado aponta para a página neste site de documentação, docs.spicyapi.ai.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

Quando há vários resultados, eles são impressos um depois do outro, e cada um começa com slug:. Se nada corresponder, ele avisa e mesmo assim termina com código de saída 0:

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

Com --json, quando nada corresponde, aparece uma lista vazia, []. Gratuito.

models list

O que faz: lista os modelos que a sua conta pode chamar hoje, com os preços que a sua conta paga.

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

Saída: total e items. Use --json, porque sem ele todos os itens saem numa linha só. Os campos mais úteis de cada item:

Gratuito. A lista de modelos conta para o limite de requisições da sua conta, então não é preciso rodá-la antes de cada geração.

models get

O que faz: mostra um modelo por completo, incluindo as configurações que ele aceita.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Saída: os mesmos campos de models list, mais inputSchema. Em inputSchema, leia required (as configurações que você precisa enviar), properties (todas as configurações permitidas e o tipo de cada uma), enum (os únicos valores permitidos), minimum e maximum (limites numéricos) e default (usado quando você deixa a configuração de fora). Os itens chamados x-ui são dicas para montar formulários; você pode ignorá-los. Gratuito.

balance

O que faz: mostra quanto dinheiro está disponível na sua conta.

spicyapi balance

Sem opções. Gratuito.

Saída: available (o que você pode gastar agora), held (reservado para tarefas que ainda estão rodando) e total, todos em dólares americanos. Também pode incluir funding, que divide o saldo entre fundos pré-pagos e verbas promocionais, inclusive quando as verbas expiram e quais modelos elas pagam. Não é preciso conferir o saldo antes de cada geração: o tasks create confere por você.

usage

O que faz: mostra quantas gerações a chave de API atual rodou e quanto elas custaram, agrupadas por dia e por modelo.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

Isso cobre setembro inteiro: --to é o primeiro dia que não entra. Deixe as duas opções de fora para ver os últimos sete dias, incluindo hoje.

Saída: from, to, currency, totalCalls, totalSpend, depois days (por dia: calls, succeeded, failed, spend) e models (os mesmos números por modelo). totalSpend só conta cobranças finais. days e models descrevem as mesmas tarefas de dois jeitos, então não some um com o outro. Para a conta inteira, e não só para uma chave, use a página Consumo do console.

Gratuito. Ele tem um limite de 30 chamadas por minuto, então use-o para conferir totais, não dentro de um loop.

tasks quote

O que faz: diz exatamente quanto uma geração custaria, sem iniciá-la e sem reservar dinheiro nenhum.

spicyapi tasks quote --model <model> --input-file <path>

Saída: quoteId, model, estimatedCost, maxCharge, currency, quantity (por exemplo, o número de segundos cobrados), unit e expiresAt. Uma cotação vale por cinco minutos.

Gratuito e sem confirmação. Use-o para comparar modelos ou configurações. Você não precisa rodá-lo antes do tasks create, que pede a própria cotação.

tasks create

O que faz: inicia uma geração de imagem ou vídeo. Isto custa dinheiro. A CLI sempre mostra o preço e pergunta antes.

spicyapi tasks create --model <model> --input-file <path> [options]

O que acontece, em ordem:

1. A CLI lê a sua entrada e confere se ela é um objeto JSON. Se você não informou nenhuma entrada, ela para aqui.
2. Se ninguém puder responder a uma pergunta, por exemplo num script, e você não tiver passado --yes, ela para aqui.
3. Ela pede uma cotação e mostra o custo estimado, a cobrança máxima, quando a cotação expira e a chave de idempotência.
4. Ela pergunta Continue? [y/N]. Só y ou yes continua. A resposta padrão é não.
5. Ela cria a tarefa pelo preço cotado. O valor estimado é reservado do seu saldo, e esse valor é também o máximo que a tarefa pode custar.
6. Sem --wait, ela mostra idempotencyKey, taskId, state (queued), estimatedCost e deadlineAt e retorna. Com --wait, ela mostra na hora Accepted: <task-id> e um comando de recuperação, espera e depois mostra idempotencyKey, accepted e a task concluída.

deadlineAt é o horário limite para a tarefa terminar antes de acabar como expired. Não é quando o seu link de download ou os seus arquivos expiram.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

No macOS e no Linux, você também pode passar a entrada direto no comando:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

Quando a espera falha com um erro (e não por um Ctrl + C), as últimas linhas repetem tudo o que você precisa, para que você não tenha que rolar a tela de volta até a linha Accepted::

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

Se o erro for de um tipo com solução conhecida, como 429 ou um erro do servidor, vem em seguida uma linha Next:. Com --json, as mesmas informações ficam no objeto de erro, como taskId, idempotencyKey e recover.

tasks wait

O que faz: espera uma tarefa que você já iniciou, até ela terminar.

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

Saída: a tarefa concluída, com os mesmos campos de tasks get, assim que o estado dela for succeeded, failed ou expired. Se a tarefa deu certo mas os arquivos ainda estão sendo copiados, ele espera mais um pouco.

Se o limite de tempo acabar, aparece Error: task … did not reach a terminal state within 600000ms. Isso não é uma falha: a tarefa continua rodando. Espere de novo, com um --wait-timeout-ms maior se precisar. Interromper uma espera nunca cancela uma tarefa. Gratuito.

tasks get

O que faz: mostra uma tarefa neste momento: o estado, o custo, os links do resultado e quando o conteúdo dela vai ser apagado.

spicyapi tasks get <task-id>

Use a mesma chave de API que criou a tarefa: outra chave recebe "não encontrado".

Campos da saída:

A saída normal termina com um resumo em linguagem simples, como Outputs expire: … ou Content: Destroyed — you removed the outputs …. Cada chamada devolve links de download novos. Gratuito.

tasks list

O que faz: lista as tarefas criadas com a chave de API atual, uma página por vez.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

Saída: items (cada um com taskId, model, state, cost, settled, createdAt, deadlineAt e completedAt), hasMore e nextCursor. Se hasMore for true, rode o mesmo comando de novo, com os mesmos --from e --to, acrescentando --cursor com o valor de nextCursor. A lista não traz links de download; use tasks get na tarefa que você quer. Gratuito.

tasks retry

O que faz: roda de novo uma tarefa failed ou expired, como uma tarefa nova, com um ID novo. Isto custa dinheiro.

spicyapi tasks retry <task-id> [options]

Ele pergunta Retry source task … Continue? [y/N]. Ao contrário do tasks create, ele não mostra o preço antes de perguntar. A tarefa nova é cobrada pelo preço atual do modelo, então, se o preço importa, confira antes com spicyapi models get <model>.

Saída: idempotencyKey, o novo taskId, sourceTaskId (a original), state, estimatedCost (o valor reservado) e deadlineAt.

• Só tarefas failed e expired podem ser repetidas, além das canceled mais antigas. Para ter outra versão de um resultado que deu certo, use tasks create.
• A entrada original é reaproveitada sem mudança, então uma nova tentativa só ajuda quando a falha foi temporária. Confira antes o errorCode; veja Repetir uma tarefa que falhou e Erros.
• Se a entrada apontava para um arquivo enviado que já expirou, a nova tentativa falha; envie o arquivo de novo e use tasks create.
• A nova tentativa mantém a configuração de retenção da tarefa original.
• Se o tasks create perdeu a conexão antes de você ver um ID de tarefa, isso não é uma tarefa que falhou. Nesse caso, siga os passos de recuperação de Retomar uma tarefa depois que a espera foi interrompida.

tasks purge

O que faz: apaga de forma permanente a mídia gerada, o resultado armazenado (os dados do resultado que ficam guardados), o prompt e os demais textos de entrada de uma tarefa concluída, na hora, em vez de esperar que eles expirem.

spicyapi tasks purge <task-id> [--yes]

Uma tarefa que ainda está queued ou running não pode passar por purge. Ela também não pode ser cancelada — não existe comando nem API de cancelamento —, então espere que ela termine com spicyapi tasks wait <task-id> e depois faça o purge.

Ele explica o que vai ser apagado e pede a sua confirmação, porque isso não pode ser desfeito. Baixe antes tudo o que quiser guardar.

Saída: taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (sempre true) e mediaDeletionPending, seguidos de uma linha que diz o que foi destruído e avisa que a mídia armazenada é removida em cerca de um minuto. Se contentState ainda for present, nada foi removido desta vez; tente de novo mais tarde.

Gratuito, e não é reembolso: o lançamento no registro de cobrança, o valor cobrado, o modelo, o estado, os horários e o ID da requisição continuam registrados. Veja Retenção e destruição.

files upload

O que faz: envia um arquivo do seu computador, como a imagem inicial de uma geração de imagem para vídeo, e devolve um endereço spicy:// para colocar na sua entrada.

spicyapi files upload <path> [--content-type <type>]

São aceitos imagens .jpg, .jpeg, .png, .webp e .gif de até 10 MiB, vídeos .mp4 e .webm e áudios .mp3 e .wav de até 90 MiB e 600 segundos. Um modelo pode definir limites próprios mais baixos.

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

Saída: copie o valor de uri, exatamente como aparece, para a configuração de arquivo do modelo, muitas vezes image_url. Ele pode ser usado até expiresAt, normalmente um dia. Depois disso, envie o arquivo de novo. O upload é gratuito.

files download-url

O que faz: cria um novo link de download para o resultado de uma tarefa concluída. Ele mostra o link; não salva o arquivo.

spicyapi files download-url <task-id> [--key <key>]

Saída: key, url e expiresAt. O link funciona por cerca de 20 minutos; abra-o num navegador ou baixe com curl. Uma tarefa que ainda não deu certo responde "não encontrado". Se o arquivo ainda estiver sendo copiado, você recebe um erro de conflito; espere alguns segundos e tente de novo. Depois que os arquivos da tarefa foram apagados, não dá para gerar um link novo. Gratuito.

webhooks verify

O que faz: se você tem um servidor que recebe callbacks da SpicyAPI (veja --callback-url), este comando confere se um callback salvo é autêntico e não foi alterado. Ele roda inteiramente no seu computador e não precisa de chave de API.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

Saída: em caso de sucesso, payload (o conteúdo do callback), payloadVersion, taskId, deliveryId (versão 2) e timestamp. Se algo não bater, ele mostra um erro e termina com código de saída diferente de zero. Gratuito.

Uma chave de assinatura é criada automaticamente quando você se cadastra, mas o valor dela nunca é mostrado. Para ter uma que você possa copiar, abra Webhooks no console e clique em Gerar (ou em Trocar, se já houver uma configurada). A chave nova aparece uma única vez. A troca vale na hora, sem período de transição: a chave antiga para de assinar imediatamente. Veja Webhooks.

Receitas comuns

Gerar uma imagem

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Escolha um ID no resultado do primeiro comando, monte o input.json com as configurações mostradas pelo segundo, depois rode o terceiro e confirme com y. O passo a passo em Seu primeiro resultado explica cada etapa.

Transformar uma imagem em vídeo

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

A imagem enviada pode ser usada por um dia. Depois disso, envie-a de novo.

Retomar uma tarefa depois que a espera foi interrompida

Uma tarefa continua rodando mesmo que o terminal feche, a rede caia, o computador entre em repouso ou a espera estoure o tempo. O jeito de voltar a ela depende do que você viu:

• Você viu Accepted: job_…, ou uma linha Recover: abaixo do erro. Você tem o ID da tarefa. Espere de novo, ou só dê uma olhada nela:

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• Você só viu a linha Idempotency-Key:, por exemplo porque a conexão caiu enquanto a tarefa estava sendo criada. Rode o mesmo comando de novo, com o mesmo modelo e a mesma entrada, e acrescente essa chave:

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  A CLI mostra o preço e pergunta de novo, mas, se a primeira tentativa tiver sido aceita, a SpicyAPI devolve essa mesma tarefa em vez de iniciar e cobrar uma segunda. Isso funciona por 24 horas com a mesma chave de API. Se a primeira tentativa nunca chegou, a tarefa é criada agora, uma única vez.

• Você não tem nenhum dos dois. Liste as suas tarefas recentes e encontre a certa pelo horário e pelo modelo:

  spicyapi --json tasks list --limit 10

Repetir uma tarefa que falhou

Primeiro, descubra por que ela falhou:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Depois leia o errorCode. 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. O tasks retry envia a mesma entrada de novo, então só ajuda quando a causa foi temporária:

A lista completa está em Erros.

Quando fizer sentido tentar de novo, rode a nova tentativa. Ela cria, e cobra, uma tarefa nova:

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Exportar o seu consumo

Salve num arquivo um mês de consumo da chave atual:

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

O arquivo traz os totais por dia e por modelo. Para uma lista tarefa por tarefa, salve spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100 do mesmo jeito, seguindo o nextCursor enquanto hasMore for true. Os números da conta inteira e as faturas ficam no console.

Rodar a CLI a partir de um script

Num script, ninguém pode responder a Continue? [y/N], então os comandos que cobram se recusam a rodar, a não ser que você acrescente --yes. Quando fizer isso:

• peça a cotação antes e confira o preço no script;
• dê a cada geração a sua própria --idempotency-key fixa, como poster-2026-09-17-v1, para que rodar o script duas vezes não cobre duas vezes;
• acrescente --json e leia o state no resultado: um comando que termina com código de saída 0 não produziu necessariamente uma tarefa bem-sucedida;
• defina limites de gasto na chave, no console.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

Custos, confirmação e segurança

Quais comandos custam dinheiro. Só tasks create e tasks retry. Os preços são em dólares americanos. Pedir cotação, listar, conferir, enviar, baixar e apagar são gratuitos.

Ver o preço antes. O tasks quote calcula o preço de uma requisição sem iniciar nada. O tasks create pede a própria cotação e mostra Estimated charge e maximum charge antes de perguntar. Quando a tarefa é aceita, o valor estimado fica reservado (held) e é também o máximo que pode ser cobrado de você. Quando a tarefa dá certo, você paga pelo que foi realmente produzido, nunca acima desse valor, e o que sobrar volta para o seu saldo.

A confirmação. Continue? [y/N] quer dizer que a resposta é não, a menos que você digite y. O --yes responde por você, então use-o só quando já souber o preço. Se a CLI rodar num lugar em que não consegue perguntar, como um script ou com uma entrada recebida por pipe, e não houver --yes, ela se recusa em vez de presumir um sim. O tasks purge pergunta do mesmo jeito, porque apagar não pode ser desfeito. O tasks retry também pergunta, mas não mostra o preço antes.

A chave de idempotência, em palavras simples. É um rótulo para uma geração, como um número de pedido. Todo tasks create e todo tasks retry mostram uma. Se a sua internet cair e você não tiver certeza de que a geração começou, rode o mesmo comando de novo com --idempotency-key e o valor mostrado: você recebe de volta a tarefa original e não é cobrado duas vezes. O rótulo vale por 24 horas com a mesma chave de API. Não o reaproveite para outra geração: a mesma chave com uma entrada diferente é recusada.

Sem cancelamento. Depois de aceita, uma tarefa não pode ser cancelada. Ctrl + C, fechar o terminal ou revogar a chave só interrompe a espera; a tarefa termina e é cobrada normalmente.

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.

Baixe o que quiser guardar. Os arquivos de resultado ficam guardados por no máximo cerca de 14 dias, ou menos, se a sua conta ou o --retention definirem assim, e depois são apagados para sempre. Os links de download duram cerca de 20 minutos, mas você sempre pode pedir um novo enquanto o arquivo existir. Os arquivos enviados podem ser usados por um dia. Por padrão, o texto do prompt é apagado depois de 30 dias. Os registros de cobrança são mantidos. Veja Retenção e destruição.

Limites de gasto. Cada chave pode ter limites diário, mensal e acumulado, definidos na página Chaves de API. Chaves novas não têm limite até que você defina um. Uma tarefa que ultrapassaria um limite é recusada antes de começar.

A sua chave. A CLI só lê a chave de SPICY_API_KEY, nunca a imprime e, nas dicas de erro, mostra no máximo os nove primeiros caracteres dela (sk-spicy-).

Mais detalhes: Cobrança, Idempotência, Execução e novas tentativas.

Solução de problemas

Procure a mensagem que você está vendo. Os erros da SpicyAPI terminam com (request req_…); informe esse valor se falar com o suporte, mas nunca envie a sua chave.

Todos os códigos de erro são explicados em Erros, e os passos de recuperação estão em Solução de problemas e recuperação.

Código-fonte

O pacote tem licença MIT e é desenvolvido abertamente em github.com/spicyapi-ai/spicy-cli. É lá que você lê o código por trás de qualquer comando desta página, relata um comportamento diferente do descrito aqui ou propõe uma mudança.

Próximos passos