Guia de integração GloopAPI
Faturamento
Entenda reservas, liquidação e armazenamento de arquivos.
Catálogos de modelos, resumos públicos de preços e cobranças reais das chamadas são informações diferentes. Antes de iniciar uma operação cobrável, confira o modelo ou ferramenta, as entradas e o orçamento. Saldo suficiente não significa permissão para chamar.
Reserva e liquidação
A aceitação pode reservar uma cota estimada. Quando o uso oficial é confirmado, a liquidação usa o preço congelado e cobra ou devolve a diferença. Cotações de vídeo por uso são estimativas, não garantias de gasto máximo. A reserva máxima das ferramentas é calculada com limites de entrada e regras congeladas, e a criação verifica o limite de custo.
status=succeeded descreve a execução; billing.status=reserved ainda indica cobrança aguardando confirmação. Um valor final nulo também não é zero. Envios desconhecidos ao serviço ou dados de uso conflitantes mantêm a reserva até verificação. O reembolso de falhas confirmadas depende do endpoint e das evidências de uso; não há garantia de que todas as falhas sejam gratuitas.
Para texto síncrono, consulte o consumo final nos registros de uso da plataforma. Para tarefas assíncronas, consulte o status de cobrança. Não gere novamente para tentar liquidar uma tarefa anterior.
Recursos de precificação de ferramentas
pricing.mode distingue flat, preço constante por chamada; input, cálculo prévio por entradas; e usage, preço por uso final. schema_version só descreve o formato da regra. Em flat, amount é o preço constante completo, inclusive zero; input/usage não expõem valores constantes que possam induzir a erro.
pricing.quote_required determina se chamadas novas exigem cotação; requires_usage indica se a liquidação final exige uso oficial confirmado, incluindo restrições da plataforma. Mesmo um preço de venda flat pode exigir cotação e uso final; decida com esses dois campos. Com requires_usage=true, max_cost_usd deve cobrir maximum_usd, e a liquidação espera o uso oficial após o sucesso. Regras input sem requisito de uso final podem liquidar pelo valor de entrada após cotar, sem esperar o uso do serviço.
metered_pricing só restringe chamadas novas que exigem uso final. Não restringe regras constantes ou por entrada sem esse requisito nem bloqueia consultas de execuções aceitas, repetições idempotentes das solicitações originais ou recuperação de cobranças congeladas. Cotações vinculam chave, versão da ferramenta, entrada normalizada e configuração de preço/origem. Um quote_id informado para ferramenta de preço constante também é sempre validado. A menor faixa mostrada no catálogo não significa que a ferramenta seja gratuita.
Retenção de arquivos e espaço
Arquivos comuns de API expiram conforme os dias de retenção do ambiente. Imagens e vídeos persistentes usam proteção por referências para retenção prolongada; expires_at=0 indica ausência de expiração fixa. O espaço ocupado e as cobranças de geração são contabilizados separadamente; o download não é garantido antes de ready.
Excluir uma tarefa persistente limpa seus resultados e libera referências removíveis; a limpeza em segundo plano remove arquivos não compartilhados. Referências compartilhadas e registros de cobrança e idempotência permanecem. Excluir arquivos ou falhar ao salvar não reembolsa automaticamente cobranças de geração já incorridas. Tentar salvar novamente solicita espaço disponível e reutiliza o resultado original sem gerar de novo.
Cota insuficiente
Em 403, 402 ou erros de cota, confira primeiro os limites da conta e da chave. A autenticação persistente permite ler histórico com chaves válidas de cota esgotada, mas tarefas novas ainda exigem orçamento. Para liquidar uma tarefa anterior, continue consultando seu registro original; não reenvie com outra chave de API ou de solicitação. Consulte Autenticação e Tarefas assíncronas e idempotência.