API de geração com IA via x402: pague por chamada, sem conta

O x402 é um protocolo de pagamento aberto que transforma o código HTTP 402 em um paywall funcional: um servidor responde a uma requisição com o status 402 Payment Required acompanhado de parâmetros de cobrança legíveis por máquina, o cliente assina uma autorização de transferência em stablecoin, repete a requisição e obtém a resposta. Sem conta, sem chave de API e sem assinaturas mensais. A Coinbase transferiu o protocolo para a Linux Foundation em abril de 2026 e, quando a x402 Foundation iniciou as operações, contava com 40 organizações participantes, incluindo AWS, Google, Stripe, Visa e Mastercard. Não se trata mais de um experimento isolado.

Resposta rápida: o endpoint x402 da BananaBanana está em https://bananabanana.pro/api/x402. Envie um POST com { "tool": "...", "arguments": {...} }, receba um 402 com o valor exato para esses parâmetros, pague em USDC na rede Base e repita a requisição. Imagens custam a partir de $0.03, vídeo a partir de $0.30 e voz a $0.01 por fração de 200 caracteres. Imagens e voz só são cobradas se o arquivo for gerado com sucesso.

A última frase descreve o detalhe que muitos textos sobre o x402 ignoram, e é nele que focaremos. Cobrar é simples; não cobrar por execuções que falham é onde a engenharia de software se torna interessante.

Como o pagamento realmente acontece

Apenas quatro passos, sendo que o seu cliente HTTP executa três deles de forma automática:

1. O agente envia uma requisição POST padrão em JSON, sem cabeçalhos de pagamento.
2. O servidor retorna 402 com a matriz accepts. O requisito de pagamento contém o valor em unidades atômicas, o endereço de recebimento, o contrato de USDC, a rede e o prazo de expiração.
3. O cliente assina uma autorização de transferência EIP-3009 para o valor exato e a codifica em Base64 no cabeçalho X-PAYMENT.
4. A mesma requisição é reenviada com o cabeçalho. O servidor entrega a assinatura ao facilitador para validação, realiza a geração e, em seguida, solicita a liquidação on-chain.

A assinatura não é uma transação de blockchain em si. É uma autorização off-chain que só se converte em transferência real quando submetida à rede. Isso permite o fluxo em duas fases: verificar primeiro, gerar em seguida e liquidar por último.

Um detalhe prático: a especificação v2 renomeia os cabeçalhos para PAYMENT-SIGNATURE e PAYMENT-RESPONSE, mas grande parte dos clientes ainda envia X-PAYMENT, que aceitamos integralmente. Ao utilizar o SDK oficial em TypeScript, essa transição é transparente.

Quanto custa uma chamada

Os preços são calculados por geração e apresentados antes de qualquer assinatura. O valor exato depende dos argumentos (uma imagem 4K custa mais que uma de 1K), portanto a resposta 402 orça a sua solicitação específica.

Um clipe de três segundos no Omni com áudio custa $0.30, sendo a opção de vídeo real mais econômica da lista. O Veo entrega fidelidade superior, mas para um clipe de 8 segundos em 1080p com áudio o custo sobe substancialmente para um rascunho inicial.

Consulte o catálogo atualizado diretamente: GET https://bananabanana.pro/api/x402 retorna todos os valores gratuitamente, sem necessidade de pagamento.

Duas requisições do início ao fim

Veja o ciclo completo com curl, com exceção da etapa de assinatura que sua biblioteca cliente x402 executa automaticamente.

# 1. Solicitar cotação. Sem cabeçalho de pagamento.
curl -s -X POST https://bananabanana.pro/api/x402 \
  -H 'Content-Type: application/json' \
  -d '{"tool":"generate_image","arguments":{"prompt":"a paper boat on still water at dawn","model":"nano-banana-pro","resolution":"2048"}}'

{
  "x402Version": 1,
  "error": "Payment required: $0.11 for generate_image.",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "110000",
    "resource": "https://bananabanana.pro/api/x402",
    "payTo": "0x7c0e9abd1c48380e27ab5bfced1be54f23ce773f",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Assine esses parâmetros, envie novamente com o cabeçalho e a segunda resposta entregará o arquivo gerado:

{
  "paid_usd": 0.11,
  "result": {
    "status": "completed",
    "images": [{ "url": "https://bananabanana.pro/api/files/..." }]
  }
}

Dois pontos técnicos essenciais para quem desenvolve servidores x402: o campo maxAmountRequired usa unidades atômicas. Como o USDC possui 6 casas decimais, $0.11 vira 110000. Além disso, extra.name deve ser estritamente idêntico ao que a função name() do contrato USDC retorna (na Base mainnet é USD Coin, e na Base Sepolia é USDC), pois ele compõe o domain separator no EIP-712. Caso haja divergência, a validação da assinatura falhará sem mensagens claras.

Como funciona o vídeo: pagamento inicial e token de reembolso

Imagens e áudio são gerados dentro do tempo limite da própria requisição HTTP (verificação → geração → liquidação). A cobrança só ocorre se o arquivo final for entregue. Havendo rejeição por filtros de segurança ou erro upstream, a assinatura não é enviada para liquidação on-chain e você não tem custos.

Com vídeo o processo é diferente: a renderização no Veo ou Omni leva de um a dez minutos, manter uma conexão HTTP aberta é inviável e a tarefa iniciada no Google não pode ser cancelada (o método interactions.cancel deles retorna 501 UNIMPLEMENTED). Portanto, o vídeo é liquidado no início, retorna um job_id e o resultado é consultado em um endpoint gratuito.

O que ocorre se um clipe já pago for rejeitado pela moderação?

Você recebe um token de reembolso no valor integral (bb_rf_…), válido por 90 dias, aplicável em qualquer chamada futura passando-o no parâmetro refund_token. Se você pagou $1.30 por um vídeo recusado por filtros, sua próxima requisição terá $1.30 de desconto. Se a nova tarefa custar menos que o valor do token, o saldo restante é devolvido em um novo token.

Não se trata de um reembolso on-chain em USDC. Nosso servidor não armazena chaves privadas e não pode fazer envios externos, apenas aceitar ou rejeitar entradas. Para a segurança de um serviço x402, não possuir chaves privadas no servidor é uma decisão de proteção sólida.

Este vídeo custou $0.30 via endpoint x402: modelo Gemini Omni Flash, 3 segundos de duração, prompt com uma tomada contínua de tinta se espalhando na água dentro de um aquário de vidro com iluminação lateral suave e ruído ambiente grave. O áudio é sintetizado diretamente pelo modelo.

Como um agente localiza o endpoint

Se o agente já tem a URL direta, não há necessidade de descoberta. Para os demais, o serviço publica um manifesto em /.well-known/x402 (e em /.well-known/x402.json).

O manifesto lista cada ferramenta como um recurso com exigências de pagamento, identificador de rede no padrão CAIP-2, endereço de recebimento e facilitador. O bloco accepts apresenta o valor mínimo de cada ferramenta em vez do teto, impedindo que um agente pague valores excessivos por engano.

Diretórios de agentes também testam os endpoints enviando requisições POST vazias. Nosso servidor responde com 402 e instruções para a chamada das ferramentas.

x402 ou conta de usuário?

Ambos os caminhos acessam os mesmos modelos generativos. Escolha de acordo com a arquitetura do seu agente.

O bônus de recarga é uma vantagem considerável: depositar $100 com cupom gera $120 de saldo (17% de desconto real), o que o x402 não oferece por não manter saldo de conta. Por outro lado, um agente autônomo com carteira própria não precisa de e-mail e inicia a geração em apenas um ciclo de requisição.

Se preferir utilizar uma conta, nosso servidor MCP é compatível com Claude Code, Cursor e VS Code, e o gerador web está disponível diretamente no navegador.

Perguntas frequentes

Preciso de uma conta na Coinbase para pagar?

Não. Qualquer carteira EVM com USDC na rede Base pode realizar pagamentos. A liquidação é processada pelo facilitador, sem exigência de cadastro prévio.

O que acontece se a geração for bloqueada pelo filtro de conteúdo?

Para imagens e voz, nenhuma cobrança é efetuada: a liquidação só ocorre após a criação do arquivo. Para vídeo, você recebe um token de reembolso integral para reutilizar em pedidos futuros.

Quais redes e tokens são aceitos?

USDC na rede principal da Base (Base mainnet), esquema exact. O manifesto em /.well-known/x402 traz o CAIP-2 chain id e o endereço do contrato do token.

Posso editar um vídeo gerado via x402?

Não pelo x402. A edição requer vínculo com uma conta (edit_video via MCP). No x402, você pode solicitar novas gerações a qualquer momento.

Por quanto tempo uma cotação de preço é válida?

O intervalo de assinatura é de 300 segundos por padrão (maxTimeoutSeconds). Os valores base seguem os preços do site e permanecem estáveis.

Faça um teste gerando uma imagem de $0.03 no endpoint ativo. Se o seu cliente já assina autorizações EIP-3009, você está a apenas quatro linhas de código de receber sua imagem.