Novas tentativas na API de imagens NSFW: evite pagar duas vezes pela mesma imagem

Seu app de personagens adultos promete uma imagem nova. O cliente toca em Gerar, o indicador de carregamento fica rodando por um tempo e a página informa que a conexão expirou. Ele toca de novo. Um minuto depois, duas imagens aparecem e o saldo cai duas vezes.

A segunda imagem pode ser linda. Ainda assim, é uma forma cara de descobrir que uma conexão expirada não significa uma geração falha.

Numa API de imagens NSFW, as pessoas chamam três ações diferentes de nova tentativa: consultar uma tarefa existente, repetir seu envio original e pagar por outra tentativa criativa. Separe essas ações. Se você tem um ID de tarefa, consulte essa tarefa. Se a resposta de criação desapareceu, repita o pedido inalterado com a chave de idempotência original. Se a tarefa terminou, mas a imagem não atende ao briefing, outra geração é uma compra nova.

Essa última distinção importa especialmente para imagens de personagens adultos. Um modelo pode terminar com sucesso enquanto suaviza a cena pedida, altera uma roupa ou produz outro rosto. Sucesso da tarefa informa que um resultado foi entregue; não promete que você vai querer usá-lo.

O que aconteceu e qual botão você deve oferecer?

Esperar, recuperar um envio e gerar uma variação nova são ações diferentes.

Uma interface útil ao criador adulto pode chamar essas ações de Consultar imagem existente, Recuperar envio, Gerar outra variação e Tentar baixar novamente. Um único rótulo Tentar de novo esconde a diferença entre uma consulta gratuita de status e a autorização de novo gasto de geração.

Se você tem um ID, mantenha a tarefa original

O fluxo assíncrono de imagens da SpicyAPI aceita um pedido, devolve um ID de tarefa e disponibiliza a imagem depois. Uma resposta de criação aceita não é a imagem concluída. A tarefa passa por estados como queued, running e succeeded; failed, canceled e expired também são estados finais.

Salve o ID assim que seu servidor o receber, antes de atualizar o navegador. Se um cliente atualizar a página, entrar novamente ou abrir o projeto em outro dispositivo, a aplicação deve recuperar essa tarefa salva em vez de enviar o prompt de novo.

Por exemplo, um criador pede um retrato noturno novo de seu personagem adulto fictício. Seu servidor recebe um ID, mas o navegador perde a conexão antes de renderizar a ficha de espera. Ao retornar, a ficha deve retomar a conexão com essa tarefa. O criador não pediu um segundo retrato simplesmente por atualizar a página.

Use GET /api/v1/jobs/recordInfo com o ID para recuperar o estado atual. A documentação de tarefas descreve pedido e resposta. Você pode usar webhook para avisos de conclusão, mas um webhook atrasado não transforma a tarefa existente numa falha. A consulta periódica continua sendo uma alternativa de recuperação.

Não transforme um limite local de espera numa decisão de cobrança. Seu navegador pode parar de esperar após 30 segundos, o pedido HTTP de saída do servidor após 60 segundos e a tarefa remota ainda estar rodando. O registro devolvido inclui um prazo de execução, deadlineAt; ele descreve a execução remota, não quanto tempo sua página mantém uma conexão aberta. A expiração do link de download do resultado é outro relógio ainda.

Na tela de espera, use uma mensagem como “Sua imagem ainda está sendo processada. Você pode sair desta página e voltar à mesma tarefa”. Não afirme um prazo exato de conclusão sem medições daquele modelo e carga específicos. A latência medida por um concorrente para imagens comuns de produto não garante prazo para seus prompts NSFW.

Se a resposta de criação se perdeu, repita o mesmo envio

O caso difícil é uma conexão que cai depois de seu servidor enviar o pedido, mas antes de receber confirmação. Você não consegue descobrir por esse erro de conexão se a plataforma aceitou o job.

A SpicyAPI oferece uma proteção real no servidor: o cabeçalho opcional Idempotency-Key. Na mesma conta e com a mesma chave de API, repetir uma chave com o mesmo modelo normalizado, entrada e URL de callback dentro de 24 horas devolve a tarefa original em vez de reservar fundos novamente. Um pedido alterado entra em conflito com essa chave. Outra chave de API da mesma conta também não pode recuperar seu mapeamento; recebe um conflito sem divulgação do ID da tarefa original.

Crie uma chave estável para a imagem pedida pelo cliente, não para cada tentativa HTTP. Um valor gerado pela aplicação, como project-8-image-12-v1, ilustra a ideia. Não inclua dados pessoais nem texto bruto do prompt. Gere e salve a chave antes de enviar o primeiro pedido de criação. Uma nova tentativa de rede a reutiliza; uma imagem realmente nova recebe outra versão ou ID de operação.

Uma sequência mínima de recuperação é:

1. Salve na aplicação a operação de imagem pretendida, o corpo original do pedido e sua chave.
2. Envie o pedido com Idempotency-Key.
3. Se a confirmação se perder, marque a operação local como aguardando confirmação.
4. Repita o corpo inalterado com a chave inalterada usando a mesma credencial de API.
5. Salve o ID de tarefa devolvido e passe a consultar seu status.

Mantenha estável o pedido exato enviado enquanto o recupera. Não peça à interface que o reconstrua a partir de controles que o cliente pode ter alterado. Se o criador mudar de retrato próximo para composição ampla, aumentar resolução, alterar o prompt ou mudar a URL de callback, já não é o envio original.

A proteção tem um limite: 24 horas não são um armazenamento indefinido de prevenção de duplicatas para sua aplicação. Depois dessa janela, não presuma que reutilizar a chave antiga recuperará um job antigo. Seu próprio mapeamento persistente entre operação e tarefa precisa lidar com retornos posteriores. Se a aceitação continuar incerta e você não identificar o job original, confira os registros de tarefas da conta ou procure suporte antes de criar automaticamente uma substituição.

Desativar o botão Gerar ajuda, mas não basta

Um botão desativado durante o carregamento impede um toque duplo comum. Não impede envios duplicados por duas abas do navegador, cliente móvel reconectando, worker em segundo plano ou reinicialização do servidor.

Sua aplicação deve associar todos esses eventos a uma única operação lógica de imagem. Uma regra de unicidade no seu banco impede que dois workers reivindiquem independentemente a mesma operação. A chave de idempotência da plataforma protege então a fronteira de criação remota. São proteções diferentes, e você precisa das duas se o app tiver mais de uma forma de enviar um job.

Considere um produto de companhia que gera opcionalmente um retrato novo após uma conversa. O usuário também pressiona o botão manual de retrato antes da confirmação daquele pedido automático. Se as duas ações visam cumprir o mesmo pedido de retrato, associe-as a uma operação. Se o botão manual pedir explicitamente uma segunda variação, mostre que é outra geração paga. Não unifique silenciosamente duas compras deliberadas nem cobre duas vezes por uma promessa.

A chave por si só não decide essa lógica de produto. Sua aplicação define o que conta como o mesmo pedido. Uma linha deduplicada localmente no banco também não ajuda quando o cliente de saída envia cada recuperação com uma chave remota nova. O valor precisa sobreviver ao caminho inteiro.

Recusa, falha técnica e imagem indesejada têm contas diferentes

Um pedido de conteúdo adulto pode terminar de várias formas. Evite a promessa geral de que gerações NSFW falhas sempre custam zero e também a afirmação oposta de que todo erro é cobrado.

Estado da tarefa e satisfação criativa diferem. Confira o registro liquidado e as exceções de cobrança específicas do modelo.

A SpicyAPI reserva um valor estimado quando aceita uma tarefa. Enquanto settled é falso, cost representa a estimativa reservada. Depois da liquidação, representa a cobrança final. Uma tarefa bem-sucedida é cobrada até o valor reservado; fundos não usados são liberados.

Uma tarefa falha ou expirada normalmente libera sua reserva. Há exceções descritas na política de reembolso, incluindo modelos cujas páginas informam que pedidos recusados ou falhos são cobrados e uso já entregue antes de um pedido interrompido. Numa tarefa de imagem recusada pelo modelo, confira a nota de cobrança dele e o registro final liquidado. Não use só o erro HTTP como explicação do saldo da conta.

Uma imagem bem-sucedida, mas suavizada, é diferente. Imagine pedir um personagem adulto fictício confiante numa cena editorial adulta específica e receber um retrato convencional. Se a tarefa terminou com sucesso e entregou resultado, insatisfação com a cena não torna essa saída uma falha técnica reembolsável. O mesmo vale para penteado errado, acessório indesejado ou expressão de que você não gosta.

Por isso, uma política útil de tentativas precisa de um limite de gasto criativo, não apenas de uma contagem de tentativas de rede. Um worker que repete toda imagem de que seu app não gosta pode continuar comprando saídas bem-sucedidas muito depois de resolver falhas técnicas.

Leia a página exata do modelo para a tarefa usada. Uma rota permissiva de texto para imagem não prova comportamento idêntico da rota de edição, e o nome da família não basta para prever todo pedido NSFW. Use apenas personagens adultos e material que tem direito de enviar; repetir pedidos não torna aceitáveis solicitações proibidas.

Repetir uma falha final cria trabalho novo

A API também tem POST /api/v1/jobs/retry, que recebe um ID de tarefa de origem e cria outra tarefa a partir de uma falha final elegível. Não transforma a tarefa antiga num job em execução novamente. Entradas atuais do modelo, permissões, disponibilidade, saldo e preços são avaliados outra vez. A origem precisa ter entrada retida e conciliação de cobrança concluída; uma tarefa ativa ou bem-sucedida não é elegível para essa ação.

Use a mesma chave de API que criou a tarefa de origem. Se aplicar uma chave de idempotência à ação de retry, ela protege essa nova tentativa específica e tem escopo na tarefa de origem. Repetir a ação pode recuperar sua tarefa recém-criada; isso difere de repetir o primeiro pedido de criação para recuperar o original.

Num app de criador, mostre isso como uma tentativa nova de geração com preço. Se o próprio prompt precisar mudar, crie um pedido novo com a entrada revisada em vez de esperar que o retry da tarefa de origem a edite. Um pedido que falhou por referência expirada também precisa de uma referência utilizável antes de outra tentativa funcionar. A liberação da cobrança original e a reserva da nova tentativa são lançamentos separados.

Quanto tentativas repetidas realmente custam

Aqui estão configurações iniciais atuais de três endpoints de imagem. Os preços descrevem geração, não uma garantia de que todo resultado atende a um briefing NSFW.

Exemplo hipotético de planejamento: jobs duplicados acidentais acrescentam $2.40 a $7.20 de tentativas criativas intencionais.

Os detalhes importam. Z-Image Turbo com expansão de prompt ligada custa $0.016 por imagem em vez de $0.010. Seedream 5.0 Pro usa 2K por padrão, que custa $0.072 em vez do preço 1K de $0.036. Selecionar explicitamente a faixa faz o cálculo corresponder ao job.

Suponha que você planeje 100 retratos finais Qwen Image 2.1 em 1K. Se cada final precisar, em média, de três tentativas criativas cobradas, seu gasto de geração será $7.20: 100 × 3 × $0.024. Se um bug de confirmação também duplicar um envio para cada final, ele acrescentará 100 × $0.024 = $2.40, elevando o gasto a $9.60. Esses valores são exemplos de planejamento, não uma taxa de sucesso medida.

Você não transforma um processo criativo de três tentativas em uma só mudando o timeout HTTP. Pode eliminar a quarta tentativa acidental. Mantenha variações intencionais e jobs duplicados acidentais em totais separados para enxergar por qual problema está pagando.

Num fluxo de criador pequeno, defina o limite antes de gerar: talvez uma imagem inicial mais duas tentativas revisadas para este espaço específico. É uma sugestão de orçamento da aplicação, não um limite da plataforma. Se as três falham no mesmo requisito, pare de comprar pedidos quase idênticos e mude a abordagem.

Uma imagem NSFW concluída não atende ao briefing: mude uma coisa relevante

Se o rosto está certo, mas cômodo ou roupa estão errados, uma edição direcionada pode ser a próxima compra melhor do que uma nova tentativa completa de texto para imagem. Preserve o resultado útil, descreva o que mudar e escolha um modelo com uma tarefa adequada de edição. Edição ainda custa dinheiro; não é uma correção gratuita incluída na geração original.

Se o mesmo pedido continua produzindo uma cena suavizada, identifique primeiro se o problema é recusa de conteúdo, interpretação conservadora de um pedido permitido ou um prompt sobrecarregado. Reenviar repetidamente um prompt idêntico não esclarece qual ocorreu. Olhe a imagem entregue e o código estável de erro, se houver, em vez de tratar a palavra NSFW como uma chave universal.

Num exemplo de planejamento sem conteúdo explícito, um briefing de retrato pode exigir um personagem adulto fictício, casaco escuro de cetim, pose sentada, luz lateral quente e cômodo sem excesso de objetos. Se todo resultado mostrar um cômodo cheio, retire detalhes secundários do cenário e preserve as instruções de personagem e luz. Se aparecer o rosto errado, passe ao fluxo apropriado com referências em vez de acrescentar adjetivos a um prompt só textual.

Quando uma variação realmente nova for necessária, use outra operação e chave. Repetir o primeiro pedido aceito com a chave original recupera a primeira tarefa; não pede ao modelo para imaginar uma segunda imagem melhor. Se alterar a seed numa variação nova, registre isso como outra tentativa criativa. Uma seed ajuda a identificar o pedido, mas não garante o mesmo personagem entre modelos distintos.

Depois das primeiras tentativas, compare o custo final por imagem utilizável, não apenas o menor preço anunciado. Uma geração de $0.010 usada quatro vezes custa $0.040. Uma de $0.024 usada uma vez custa $0.024. Esse cálculo não prova que o segundo modelo seja mais confiável; informa o que medir no seu próprio briefing de personagem.

Quando uma imagem existente não baixa

Não regenere uma imagem bem-sucedida porque o download deu erro. O arquivo pode continuar existindo enquanto o link temporário de acesso já não funciona, ou sua aplicação pode ter falhado ao copiá-lo.

Guarde a tarefa concluída e a identidade do arquivo de saída. Recupere uma rota atual autorizada de download enquanto a saída estiver retida e então tente transferir esse arquivo de novo. Não anexe a chave de API a uma URL de mídia assinada separada. Confirme que o destino realmente contém os bytes antes de mostrar Salvo na biblioteca do cliente.

O guia de entrega de mídia aborda copiar resultados para armazenamento que você controla. Para um criador adulto, isso também delimita a privacidade: uma imagem gerada ou referência não vira material de galeria pública só porque a cópia funcionou. A recuperação deve preservar o acesso privado pretendido.

Se a saída original já foi apagada conforme a política efetiva de retenção da tarefa, um ID não restaura os bytes ausentes. Uma substituição seria outra geração e pode ter aparência diferente. Explique essa distinção ao cliente em vez de substituir silenciosamente um retrato antigo por outro recém-cobrado.

Faça a próxima ação do cliente corresponder à cobrança

Mostre juntos status da tarefa existente e cobrança liquidada. Se o job continuar sem resolução, mantenha seu lugar no projeto sem apresentar uma nova tentativa paga como única saída. Se falhou, mostre o motivo e se o valor reservado foi liberado. Se funcionou, separe Baixar novamente de Gerar outra variação.

Para suporte, evidências úteis são ID de tarefa, ID de pedido quando disponível, horário, valor e breve descrição do problema. Criar dois IDs de tarefa diferentes é distinto de cobrar duas vezes uma tarefa. A política de reembolso pede especificamente que clientes informem cobranças duplicadas, cobranças acima da reserva, saídas bem-sucedidas não entregues ou reservas de tarefas falhas não devolvidas em 24 horas. Não coloque chaves de API, links assinados de mídia nem prompts criativos sensíveis em logs comuns ou capturas de suporte.

Um criador deve entender o histórico como “um retrato pedido, um envio recuperado, um resultado entregue”, não como uma lista de tentativas HTTP invisíveis. Esse é o resultado desejado: recuperação de rede preserva a compra original, enquanto outra tentativa criativa é uma decisão deliberada com preço visível.