Faturamento

Dinheiro, não créditos

Os preços são informados em dólares americanos: “$0,008 por imagem”, “$0,042 por segundo de saída”. Saldo pré-pago, valores promocionais e linhas de crédito são denominados em dólares, mas um limite de crédito não é saldo em dinheiro.

A ausência de créditos como unidade é intencional. Um sistema de créditos adiciona uma conversão entre “recarregue X, receba Y de bônus” e “quanto vale um crédito”, dificultando o cálculo do custo real por unidade. O preço exibido é o preço que você paga.

Como funciona o pagamento

1. Adicione saldo primeiro. Uma conta nova começa com $0 de saldo, e não há plano gratuito. Uma tarefa enviada antes da recarga é recusada com 40201 e não custa nada.
2. Quando uma tarefa é aceita, o preço estimado fica reservado. Isso é uma reserva. O dinheiro continua sendo seu, mas não pode pagar outra tarefa ao mesmo tempo.
3. Se a tarefa for concluída com sucesso, você paga pelo uso efetivo, nunca mais que a reserva. Qualquer valor restante volta ao saldo.
4. Tarefas com falha ou expiradas 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 expressamente essa exceção. Confira settled e cost para saber a cobrança final.
5. Limites de gastos definidos por você em cada chave de API impedem que um script descontrolado esgote o saldo.

O restante desta página explica cada etapa em detalhes.

Adicionar saldo

Adicione saldo em Faturamento no console, por cartão, criptomoeda ou transferência manual quando essa opção estiver disponível. Você também pode ativar a recarga automática para que tarefas longas não parem por saldo baixo. O saldo pago não expira; valores promocionais expiram na data indicada em Faturamento.

Para o passo a passo sobre formas de pagamento, prazo de recebimento e recarga automática, veja Configuração da conta. Recargas geralmente não são reembolsáveis em dinheiro; a política de reembolso lista as exceções, como cobranças duplicadas.

Três etapas

Toda tarefa passa pelas mesmas três etapas de faturamento. Você não precisa fazer nada; a explicação ajuda a interpretar o histórico de saldo com segurança.

Consultar o saldo

A forma mais rápida é a página Faturamento do console: ela mostra saldo disponível, valor reservado e todas as movimentações. Por código, chame:

GET /api/v1/chat/credit

curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

const res = await fetch('https://api.spicyapi.ai/api/v1/chat/credit', {
  headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` },
});
const body = await res.json();
if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);

const balance = body.data;
console.log(balance.funding ?? balance);

import os, requests

res = requests.get(
    "https://api.spicyapi.ai/api/v1/chat/credit",
    headers={"Authorization": f"Bearer {os.environ['SPICY_API_KEY']}"},
)
body = res.json()
if body["code"] != 200:
    raise RuntimeError(f'{body["code"]} {body["msg"]}')

balance = body["data"]
print(balance.get("funding", balance))

{
  "code": 200,
  "msg": "success",
  "data": {
    "available": "128.42",
    "held": "0.36",
    "total": "128.78"
  }
}

Quando os recursos elegíveis para o modelo e o momento escolhidos não cobrem a estimativa, createTask retorna 40201. Expiração de crédito, limites esgotados e valores pendentes por recuperação de pagamentos também podem afetar a aceitação. Não substitua as verificações do servidor por uma checagem no cliente de available positivo ou negativo.

Você não precisa conferir o saldo antes de cada geração: a aceitação da tarefa já aplica as verificações de saldo disponível e limites de gastos.

// Keep the exact decimal string for display
const usd = task.cost;

from decimal import Decimal
usd = Decimal(task["cost"])   # not float()

Limites de gastos

Um limite de gastos define o valor máximo que pode ser gasto. Até seis limites se aplicam a uma tarefa; o primeiro atingido recusa a tarefa com 40202, antes de qualquer criação ou reserva:

Limites diários reiniciam às 00:00 UTC; os mensais seguem o mês do calendário UTC e reiniciam no dia 1. Um limite total nunca reinicia. Se o limite da plataforma for atingido, tente após 00:00 UTC ou contate o suporte se isso continuar acontecendo.

Uma reserva ainda não liquidada conta para todos os limites, total, mensal e diário, até a liquidação da tarefa, independentemente do dia ou mês em que ela cair: o dinheiro ainda não foi gasto, mas também não pode ser gasto duas vezes. Limites de equipe são explicados em Console e equipes.

Os limites existem para proteger você. Um laço descontrolado que consome um valor alto em poucas horas é um incidente comum neste setor e quase sempre acontece em uma conta sem limite definido.

Histórico financeiro

A página Faturamento do console lista todas as movimentações com rótulos simples, como Recarga, Reservado, Cobrado e Devolvido. Ao baixar a lista por Exportar CSV, a coluna kind contém um destes códigos estáveis:

Valores de bônus são registrados separadamente do que você pagou porque um reembolso de pagamento, devolvido ao cartão, cobre somente o valor pago; um bônus não tem valor em dinheiro. Isso não tem relação com as entradas refund acima, que devolvem ao saldo a reserva de uma tarefa com falha.

Essas movimentações são mantidas por 10 anos, separadamente do conteúdo das tarefas, ficando disponíveis para conciliação e disputas muito depois de prompts e resultados terem sido apagados. Veja Retenção de dados.

Faturas e demonstrativos de uso

Você pode emitir dois documentos em Faturamento → Faturas no console, ambos disponíveis em PDF:

Preencha seus dados uma vez no topo de Faturamento → Faturas. Nome da empresa ou seu nome, endereço linha 1, cidade e país são obrigatórios; número fiscal, como VAT ou GST, é opcional. Eles são impressos exatamente como informados: você fornece os dados, e nós não verificamos nenhum deles, nem o número fiscal. Somente caracteres latinos, gregos e cirílicos podem ser impressos; escreva o nome de uma empresa japonesa ou coreana na forma romanizada registrada. Um documento já emitido mantém os dados usados na criação; alterações posteriores afetam apenas novos documentos.

• Cada recarga paga e cada mês encerrado podem ser documentados uma vez. Se o documento já existe, baixe-o em vez de emitir outro.
• Para corrigir dados, escolha Reemitir: o documento antigo é marcado como anulado, e outro com novo número cobre o mesmo item. Use Anular sem substituir somente quando o documento corresponder à recarga ou ao mês errado.
• Os extratos da conta, mais abaixo na mesma página, são diferentes: um registro mensal fixo de todas as movimentações para sua contabilidade. Não são recibos nem documentos fiscais.

Os impostos aparecem como zero: somos uma empresa dos EUA, não recolhemos nem repassamos VAT, GST ou imposto sobre vendas em seu nome, e todos os documentos incluem um aviso de responsabilidade tributária do destinatário. Portanto, cabe a você contabilizar os tributos devidos em seu local. Uma fatura emitida nunca é editada: ela é anulada e reemitida, com registro do motivo e da substituição.

Unidades de cobrança

Um modelo tem exatamente uma unidade de cobrança.

Você não precisa adivinhar o nome: quantityField no endpoint do catálogo o informa por modelo, e uma string vazia significa uma unidade por chamada.

Um modelo pode ter preços diferentes para faixas diferentes. Resolução, duração, opções de áudio e mídia de referência podem afetar o orçamento conforme o schema. pricing[].variant identifica uma faixa do cartão de preços; não há campo variant no corpo da solicitação. Não presuma que esse rótulo sempre possa ser enviado como resolution nem calcule todos os modelos como preço inicial × duração. Envie a entrada completa a jobs/quote para obter a estimativa exata e o limite da cobrança.

Duração cobrada em blocos inteiros

A maioria dos modelos per_second cobra a duração exata produzida. Alguns cobram por blocos fixos: a duração medida é arredondada para cima até o próximo bloco inteiro antes de calcular o preço. Com blocos de 8 segundos, um clipe de 6 segundos e um de 8 segundos custam o mesmo, e um de 9 segundos custa dois blocos. Nem todo modelo cobrado por segundo funciona assim: isso só se aplica aos endpoints que declaram essa regra, e cada um a informa em sua página.

Esses endpoints têm outra característica em comum, que torna o arredondamento visível no orçamento: obtêm a duração de um vídeo fornecido por você, não de um valor duration_seconds escolhido. Ninguém sabe a duração do resultado até ler o clipe. Seu quantityField é vazio, e o valor informado antes do envio corresponde ao pior caso: o clipe mais longo aceito pelo endpoint:

{
  "estimatedCost": "0.96",
  "maxCharge": "0.96",
  "quantity": "32",
  "unit": "per_second"
}

Os valores são ilustrativos; quantity aqui é um limite em segundos, não uma medição. O valor do orçamento é reservado; a cobrança final é calculada pela duração arredondada e nunca ultrapassa a reserva. O restante é liberado na liquidação, exatamente como nas três etapas acima.

Duas consequências merecem planejamento:

• Planeje o orçamento pelo valor cotado, não pelo seu clipe. Até a liquidação, o dinheiro reservado é o máximo e conta nos limites de gastos como qualquer outra reserva.
• Um clipe curto ainda custa um bloco inteiro. Cortar de 9 para 8 segundos pode reduzir pela metade o preço de um endpoint com blocos de 8 segundos; cortar de 8 para 5 não altera nada.

As unidades e os preços exatos estão na página de preços e na página de cada modelo.

Descontos e promoções para clientes

Ofertas podem valer para todos ou para uma conta, em todos os modelos ou em modelos selecionados. Ofertas contínuas valem até serem desativadas; ofertas com prazo valem somente entre seu início e fim reais. Preços específicos de uma conta se aplicam quando ela entra no site ou solicita um orçamento com sua chave de API e nunca são publicados como preço de outro cliente.

Ofertas não se acumulam. O menor preço para o qual você é elegível se aplica automaticamente. Em uma cobrança padrão de $10, uma oferta pública de 10% e um desconto de conta de 20% resultam em $8, não em $7,20 por descontos combinados. Quando uma oferta termina ou é desativada, novos orçamentos usam a melhor oferta elegível restante ou o preço padrão se não houver outra.

Ofertas na página inicial, no catálogo e nas páginas dos modelos ajudam na comparação. Obtenha a estimativa real por jobs/quote com sua identidade, modelo e entradas completas. Uma contagem regressiva não reserva um preço: atualize o orçamento após mudanças em oferta, entradas ou preço. Tarefas aceitas mantêm o preço fixado mesmo que a oferta termine durante a execução, e a cobrança final não pode exceder o valor reservado na aceitação.

Ofertas se aplicam automaticamente às cobranças de uso da API, não ao valor da recarga, e não dão cashback de recarga. Exemplos de orçamento diário ou mensal projetam o preço atual; uma oferta com prazo pode terminar antes desse período, portanto confira também seu término.

Valores promocionais e linhas de crédito

GET /api/v1/chat/credit mantém available, held e total e pode incluir um detalhamento funding. Respostas antigas podem omitir funding; dados ausentes não significam zero. Use client.getBalance() no SDK ou spicyapi balance --json na CLI.

• funding.prepaidAvailableUsd contém saldo disponível pré-pago ou antigo sem restrições; grantAvailableUsd soma os valores promocionais ativos. Cada entrada de grants informa os valores concedido, disponível, reservado e gasto, além de status, início, expiração e modelSlugs. Uma lista de modelos vazia significa todos os modelos; caso contrário, o valor paga apenas pelos modelos listados. A lista contém até 100 concessões, priorizando as que têm saldo restante ou reservado e depois ordenando da mais recente para a mais antiga. grantsHasMore indica registros adicionais. Não substitua o total da conta pelo subtotal da lista visível.
• funding.credit descreve uma linha aprovada de pagamento posterior. limitUsd é seu limite; availableUsd, o crédito elegível não usado; usedUsd, o principal já contabilizado e ainda devido; heldUsd, o crédito reservado para tarefas aceitas; e expiresAt, a expiração. O limite de crédito não é recarga, valor promocional nem saldo em dinheiro. Expiração, desativação ou limite excedido restringem novas solicitações; a dívida existente continua devida.
• Valores promocionais não podem ser sacados. Descontos definem o preço da solicitação; valores promocionais e crédito determinam como esse preço é financiado. Uma concessão promocional não reduz o preço exibido do modelo. Seu escopo de modelos e validade se aplicam, e valores não usados podem expirar ou ser revogados. Tarefas com falha e reservas não usadas devolvem recursos à fonte original; isso não reativa uma concessão expirada ou revogada.
• Um funding.cashShortfallUsd positivo indica falta de saldo decorrente de recuperação externa de pagamento. Valores promocionais e crédito não podem cobri-la; novas chamadas ficam bloqueadas até que seja coberta. Um available negativo pode, por sua vez, refletir uso de crédito aprovado. Não deduza recusa pelo sinal nem o some diretamente ao limite de crédito. A aceitação verifica no servidor fontes de recursos, elegibilidade do modelo, validade e limites de gastos.

Os valores continuam sendo strings decimais exatas em USD, e as datas usam RFC3339. Informe o fuso ao exibir datas. A página de faturamento do console mostra detalhes dos recursos e das concessões; mudanças só entram em vigor após aprovação manual de um administrador. Para perguntar sobre concessões ou linhas de crédito, abra uma conversa em Suporte no console ou envie e-mail a support@spicyapi.ai. A API pública não oferece operações para aumentar seus próprios limites ou conceder valores promocionais.

Uso da chave de API atual

Para um gráfico de gastos por dia e modelo de toda a conta ou equipe, use Faturamento → Uso no console. O endpoint da API abaixo informa somente o uso da chave que faz a chamada:

curl 'https://api.spicyapi.ai/api/v1/usage?from=2026-09-01&to=2026-09-06' \
  -H "Authorization: Bearer $SPICY_API_KEY"

As datas usam UTC [from,to); este exemplo inclui de 1 a 5 de setembro. Omita as datas para consultar os últimos sete dias, incluindo hoje; o intervalo máximo é de 92 dias. Os resultados pertencem apenas à chave de API atual. Não há parâmetro para outra chave ou relatório da conta inteira; use chat/credit para consultar o saldo da carteira.

data.totalCalls conta todas as tarefas; data.totalSpend inclui apenas cobranças liquidadas. days e models agrupam as mesmas tarefas por data de criação e modelo, com strings decimais exatas em USD. Reservas pendentes ficam de fora, e uma liquidação tardia pode atualizar datas anteriores. Histórico de tarefas oculto continua incluído; datas sem chamadas são omitidas. Não some os dois agrupamentos.

Use client.getUsage({ from, to }) no SDK ou spicyapi usage --from 2026-09-01 --to 2026-09-06 na CLI. Este endpoint tem um limite próprio mais restrito; veja Limites de solicitações.