Checklist de produção

Uma demo precisa de uma requisição. Um produto precisa aguentar timeouts, webhooks duplicados, links expirados e uma chave vazada. Passe por esta lista antes do lançamento.

Chaves

• A chave fica no cofre de segredos do seu servidor, nunca no navegador nem no pacote de um app.
• Cada ambiente e cada serviço tem sua própria chave, para revogar uma sem mexer nas outras.
• Chaves de produção só chamam os modelos que você usa e têm limite diário de gasto.
• Você sabe rotacionar uma chave sem derrubar nada (Autenticação).

Criar tarefas

• Todo createTask envia um Idempotency-Key derivado do seu próprio ID de trabalho, gerado uma vez e reutilizado em cada nova tentativa.
• Só 429, 500, 503 e 50301 são repetidos, com espera crescente e Retry-After (Erros).
• 400, 40004 e outros erros de "corrija a requisição" são mostrados ou registrados, não repetidos.
• Se você mostra preços, cota antes, passa quoteId e expectedCredits e trata 40901.
• Saldo baixo (40201) chega a uma pessoa — alerta, e-mail, banner — antes de os usuários perceberem.

Receber resultados

• As tarefas levam callBackUrl; seu endpoint verifica a assinatura e recusa timestamps antigos.
• O handler do webhook responde 2xx rápido e faz o trabalho em segundo plano.
• Entregas duplicadas são ignoradas pelo request_id.
• Uma varredura periódica lê as tarefas cujo webhook nunca chegou.
• Seu código trata qualquer estado diferente de succeeded, failed, expired e canceled como "ainda rodando".

Arquivos

• Arquivos prontos são copiados para o seu próprio armazenamento (ou para a biblioteca de assets) em vez de apontar para a URL assinada, que expira em uns 20 minutos.
• Você guarda taskIds, não links assinados.
• O código de download não envia a chave de API para a URL assinada.
• Arquivos de referência são links HTTPS públicos para o próprio arquivo, uploads ou assets — não páginas de compartilhamento.

Custos

• Você conhece a unidade de preço de cada modelo (por imagem, por segundo, por requisição) e as configurações que a encarecem.
• Prévias e testes usam a resolução mais barata e a duração mais curta.
• Um limite de gasto para loops descontrolados antes que eles zerem o saldo.
• Você confere credits e settled em vez de supor que a estimativa foi cobrada.

Monitoramento

• Você registra request_id, taskId, code e errorCode em toda falha.
• Você acompanha a proporção de tarefas failed por modelo; um salto repentino costuma indicar mudança no prompt, na entrada ou no modelo.
• Você mede por modelo o tempo de createTask até o webhook e alerta sobre valores fora da curva.
• Alguém do time sabe onde ficam os logs e a página de uso do console da API.

Conteúdo

A PopNow é um serviço para o público geral. Os modelos aplicam regras de conteúdo próprias, e as requisições recusadas falham com content_rejected. Se os seus usuários escrevem os prompts, explique na sua própria interface por que uma requisição foi recusada, em vez de mostrar um erro cru, e deixe que eles a alterem.