Cobrança

Preços e saldos são em dólares americanos. estimatedCost, cost, available, held e total são strings decimais sem símbolo de moeda. Para contabilidade, use tipo decimal em vez de ponto flutuante.

API

{
  "available": "128.42",
  "held": "0.36",
  "total": "128.78"
}

Verbas promocionais e limite de crédito

GET /api/v1/chat/credit pode incluir funding para separar saldo pré-pago, verbas promocionais e crédito aprovado. A ausência desse objeto em uma resposta antiga não significa saldo zero. Use client.getBalance() ou spicyapi balance --json. Valores continuam sendo strings decimais exatas em USD, e datas usam RFC3339.

prepaidAvailableUsd mostra os recursos pré-pagos disponíveis; grantAvailableUsd soma as verbas atualmente válidas. Cada item de grants contém availableUsd, heldUsd, spentUsd, status, startsAt, expiresAt e modelSlugs. Uma lista vazia permite todos os modelos. As verbas só podem ser usadas dentro da validade e no escopo indicado, sem possibilidade de saque. São exibidas até 100 concessões, primeiro as que têm saldo restante ou reservado e, em cada grupo, as mais recentes. grantsHasMore indica que há mais registros; não use o subtotal da lista como total da conta.

credit.limitUsd é o teto aprovado, não saldo em dinheiro. credit.availableUsd é o crédito restante, usedUsd é a dívida já apurada e ainda não paga, e heldUsd é a parcela reservada. Vencimento, desativação ou excesso de limite restringem novas chamadas sem quitar a dívida. available pode ser negativo devido ao uso de crédito aprovado; o sinal sozinho não determina se uma chamada será aceita. cashShortfallUsd positivo indica falta de recursos após recuperação de um pagamento externo, que não pode ser coberta por verbas promocionais ou crédito. A validação final é do servidor.

Descontos definem o preço; verbas e crédito definem a fonte de pagamento. Reservas liberadas voltam à origem sem reativar verbas vencidas ou revogadas. Mudanças exigem aprovação manual. Fale com o suporte: a API pública não permite aumentar o próprio saldo. No extrato, grant_expire indica vencimento e grant_revoke revogação.

Uso da chave API atual

GET /api/v1/usage agrega apenas as tarefas da chave API usada na autenticação. from e to são datas UTC no formato YYYY-MM-DD. O intervalo [from,to) inclui o início e exclui o fim, com limite de 92 dias. Por padrão, to é a data de amanhã em UTC e from fica sete dias antes de to. totalSpend e cada spend são strings decimais em USD que somam apenas cobranças reais já liquidadas, sem reservas pendentes. As tarefas são agrupadas pela data de criação; uma liquidação tardia pode alterar valores de dias anteriores. A resposta não representa o saldo da conta nem o orçamento restante da chave.

Descontos por conta e promoções

As ofertas podem atender todos os usuários ou uma conta específica, em todos os modelos ou apenas nos selecionados. Ofertas permanentes valem até a desativação; promoções temporárias valem entre o início e o fim reais. Preços exclusivos exigem login na conta correspondente ou uma cotação com a chave API dessa conta.

Os descontos não se acumulam: o menor preço elegível é aplicado automaticamente. Com preço normal de $10, promoção de 10% e desconto de conta de 20%, o preço é $8. Após o término, novas cotações usam a melhor oferta ainda válida ou o preço normal.

A contagem regressiva não reserva o preço. Consulte jobs/quote com sua identidade e todos os parâmetros; solicite outra cotação se a oferta, o preço ou as entradas mudarem. Uma tarefa aceita mantém o preço fixado mesmo se a promoção terminar durante a execução. A cobrança final não excede o valor reservado.

Os descontos são aplicados automaticamente ao consumo da API, não ao valor da recarga, e não oferecem cashback de recarga. Orçamentos diários ou mensais projetam o preço atual; uma promoção pode terminar antes do fim desse período. Confira também a data de encerramento.

Unidades de cobrança

pricing[].unit é per_image, per_second, per_request ou per_1k_tokens. Leia quantityField e pricing[].variant no catálogo em vez de adivinhar campos de entrada.

Reserva, liquidação e liberação

createTask reserva estimatedCost. succeeded é liquidada pelo uso real; failed, expired e registros canceled históricos liberam tudo. Uma nova tarefa aceita não pode ser cancelada. Tarefa e reserva são criadas em uma transação, e a liquidação de cada tarefa termina exatamente uma vez.

Saldo e tetos

GET /api/v1/chat/credit retorna available, held e total. Saldo insuficiente é 40201; os tetos diário, mensal e acumulado da chave, e o teto diário da plataforma, são 40202. Tetos diários reiniciam à meia-noite UTC e os mensais no dia 1 à meia-noite UTC; um teto acumulado nunca reinicia. 0 explícito significa ilimitado.

Razão contábil

O ledger é append-only e registra separadamente topup, bonus, hold, settle, refund, adjust e chargeback. Essas movimentações de saldo não são apagadas com o conteúdo das tarefas e continuam visíveis no histórico de cobrança.

Consulte o contrato OpenAPI 3.1 para ver a definição completa dos campos.