> ## Documentation Index > Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # API de moderação > Analise prompts e imagens antes que seu produto de IA os gere e receba um veredito de permissão, sinalização ou bloqueio, com uma pontuação para 17 categorias de conteúdo. Envie texto, uma imagem ou ambos e receba um veredito. Veja suas análises faturáveis e sua próxima cobrança. ## Visão geral A API de moderação analisa a entrada do usuário antes que seu produto de IA a utilize para gerar conteúdo. Você envia o texto de um prompt, uma imagem ou ambos, e a Dodo Payments retorna um veredito de `allow`, `flag` ou `deny`, juntamente com uma pontuação para cada categoria de conteúdo. Use-a antes de qualquer modelo de geração de imagens, vídeos ou texto que receba entradas dos seus usuários. A API de moderação fica ativada por padrão para todas as empresas e usa sua chave de API existente da Dodo Payments, portanto não é necessário fazer nenhum cadastro. A Dodo Payments pode desativá-la para uma empresa específica; nesse caso, as chamadas retornam `403` com `MODERATION_DISABLED`. ## Por que criamos a API de moderação Um produto de geração de IA cria novo conteúdo a partir do que seus usuários digitam. Você não pode revisar cada prompt manualmente, e uma única saída prejudicial pode colocar sua empresa em risco. Como seu Merchant of Record, a Dodo Payments é legal e reputacionalmente responsável pelo que é vendido pela plataforma. A [Política de Aceitação de Comerciantes](/miscellaneous/merchant-acceptance) analisa ferramentas de geração de conteúdo de IA e não permite personificação, deepfakes ou conteúdo explícito, incluindo conteúdo gerado por IA. Uma conta que gere conteúdo prejudicial, chargebacks excessivos ou sinalizações de parceiros de pagamento pode ser colocada sob análise ou suspensa. Criamos a API de moderação para que você possa interromper esse conteúdo antes que seu modelo o crie: * **Analise antes de gerar.** Um prompt bloqueado nunca chega ao seu modelo, portanto nenhuma saída prejudicial é criada e você não gasta recursos computacionais com ela. * **Cubra as categorias importantes para a geração.** A análise pontua 17 categorias, incluindo semelhança com uma pessoa real, imagens íntimas não consensuais, linguagem que indica menores de idade e a combinação de uma pessoa real com conteúdo sexual que caracteriza um deepfake sexual. * **Integre sem outro fornecedor.** A API funciona com sua chave de API da Dodo Payments, e a tarifa é debitada do seu saldo. Não há contrato, fatura ou conta separada. * **Mantenha o conteúdo dos usuários privado.** A Dodo Payments não armazena nem registra o texto e as imagens analisados. A API de moderação é uma ferramenta para sua própria aplicação de políticas. Ela não substitui a Política de Aceitação de Comerciantes, e você continua responsável pelo que seu produto gera. ## Como funciona Chame a API de moderação pelo seu backend depois que o usuário enviar um prompt e antes da execução do seu modelo: ```mermaid theme={null} flowchart LR A[User submits a prompt] --> B[Your backend calls POST /moderation/screen] B -->|allow| C[Generate] B -->|flag| D[Apply your own policy] B -->|deny| E[Block the request] B -->|error, no verdict| E ``` Cada chamada corresponde a uma **análise**. O texto e uma imagem enviados na mesma chamada contam como uma única análise. ### Vereditos O campo `decision` contém o veredito: | Veredito | Significado | O que fazer | | -------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `allow` | O conteúdo foi aprovado. | Gere o conteúdo. | | `flag` | O conteúdo ultrapassou o limite de uma categoria que exige análise humana. Não é uma recusa provisória. | Aplique sua própria política. Você pode bloquear, enviar para análise ou gerar o conteúdo. | | `deny` | O conteúdo não deve ser gerado. | Bloqueie a solicitação e mostre um erro ao usuário. | Não gere conteúdo quando não receber um veredito. Um `503` significa que a Dodo Payments não conseguiu produzir um veredito, e um timeout ou erro de rede faz com que você fique sem um. Trate todos esses casos como um bloqueio e peça ao usuário para tentar novamente. ## Analisando um prompt Para analisar um prompt, envie uma solicitação `POST` para `/moderation/screen` com pelo menos um entre `text` e `image`. A solicitação aceita três campos: | Campo | Tipo | Descrição | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | O texto a ser analisado, com até 8.000 caracteres. | | `image` | string | A imagem a ser analisada, em base64, com ou sem o prefixo `data:image/...;base64,`. | | `request_id` | string | Opcional. Seu identificador para esta análise, como um ID de geração, com até 128 caracteres e sem caracteres de controle. A resposta o retorna sem alterações. | Os SDKs de TypeScript e Python disponibilizam o endpoint como `client.moderation.screen()`. Este exemplo bloqueia a geração em `deny`, em `flag` e em qualquer erro: Os exemplos usam o modo live, pois somente o modo live executa o modelo de moderação. O modo de teste retorna [vereditos simulados](#testing-your-integration) e nunca analisa o conteúdo. As análises no modo live são faturadas. ```typescript Node.js expandable theme={null} import DodoPayments from 'dodopayments'; const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY, environment: 'live_mode', }); async function generateImage(prompt: string, generationId: string) { let verdict; try { verdict = await client.moderation.screen({ text: prompt, request_id: generationId, }); } catch (err) { // No verdict: do not generate. throw new Error('Moderation is unavailable. Try again in a moment.'); } if (verdict.decision !== 'allow') { throw new Error('This prompt cannot be generated. Revise it and try again.'); } return myModel.generate(prompt); } ``` ```python Python expandable theme={null} import os from dodopayments import DodoPayments, APIError client = DodoPayments( bearer_token=os.environ["DODO_PAYMENTS_API_KEY"], environment="live_mode", ) def generate_image(prompt: str, generation_id: str): try: verdict = client.moderation.screen(text=prompt, request_id=generation_id) except APIError: # No verdict: do not generate. raise RuntimeError("Moderation is unavailable. Try again in a moment.") if verdict.decision != "allow": raise ValueError("This prompt cannot be generated. Revise it and try again.") return my_model.generate(prompt) ``` ```bash cURL theme={null} curl -X POST https://live.dodopayments.com/moderation/screen \ -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "a watercolor painting of a lighthouse at sunset", "request_id": "gen_7Hc2k9" }' ``` O exemplo trata `flag` como `deny`. Se seu produto permitir algum conteúdo sinalizado, verifique `triggered` para decidir por categoria. Analise o texto escrito pelo usuário, não o template de prompt que você adiciona ao redor dele. Seu próprio template é igual em todas as chamadas e não acrescenta nada à análise. ### Analisando imagens Envie uma imagem para analisar uma imagem de referência carregada ou uma imagem gerada antes de exibi-la. A imagem deve atender aos seguintes requisitos: * O formato deve ser JPEG, PNG, WebP, GIF ou BMP. * A string base64 deve ter no máximo 6.991.530 caracteres, e a imagem decodificada deve ter no máximo 5 MiB. * A imagem deve ser um único quadro estático. Imagens GIF e WebP animadas são rejeitadas. * A maior dimensão deve ter pelo menos 32 pixels. Uma imagem que não passe por uma dessas verificações retorna `400` com `MODERATION_INVALID_IMAGE` ou `413` com `MODERATION_INPUT_TOO_LARGE` quando for grande demais. Para analisar uma imagem, leia o arquivo, codifique-o como base64 e envie-o em `image`. Para analisar uma imagem e seu prompt juntos, envie `text` e `image` na mesma chamada. Isso conta como uma única análise. Este exemplo usa o `client` do exemplo anterior: ```typescript Node.js expandable theme={null} import { readFile } from 'node:fs/promises'; async function screenImage(path: string, prompt: string, generationId: string) { const image = (await readFile(path)).toString('base64'); const verdict = await client.moderation.screen({ image, // or `data:image/png;base64,${image}` text: prompt, // optional: screen the prompt with the image request_id: generationId, }); return verdict.decision === 'allow'; } ``` ```python Python expandable theme={null} import base64 def screen_image(path: str, prompt: str, generation_id: str) -> bool: with open(path, "rb") as f: image = base64.b64encode(f.read()).decode("ascii") verdict = client.moderation.screen( image=image, # or f"data:image/png;base64,{image}" text=prompt, # optional: screen the prompt with the image request_id=generation_id, ) return verdict.decision == "allow" ``` ```bash cURL expandable theme={null} # Builds the JSON body with jq, so a large image does not hit the shell argument limit. base64 < reference.png | tr -d '\n' \ | jq -Rs '{image: ., text: "turn this photo into a watercolor painting", request_id: "gen_7Hc2k9"}' \ | curl -X POST https://live.dodopayments.com/moderation/screen \ -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \ -H "Content-Type: application/json" \ --data @- ``` Trate os erros de uma análise de imagem da mesma forma que os de uma análise de texto: se a chamada gerar uma exceção, não gere conteúdo. ## Lendo a resposta A resposta retorna o veredito e as evidências que o fundamentam: | Campo | Descrição | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `decision` | O veredito: `allow`, `flag` ou `deny`. | | `triggered` | As categorias cuja pontuação ultrapassou o limite da categoria. Pode estar vazio em um `flag` da verificação geral. | | `compound_triggered` | `true` quando a semelhança com uma pessoa real e o conteúdo sexual ultrapassaram juntos o limite combinado, caracterizando um deepfake sexual. | | `categories` | A probabilidade, de 0 a 1, de o conteúdo se enquadrar em cada categoria. | | `provenance` | Como cada pontuação foi medida: `targeted` por uma verificação daquela categoria ou `broad` pela verificação geral que abrange todas as categorias. | | `notes` | Motivos legíveis para a decisão. A redação pode mudar; não faça o parsing desse campo. | | `normalized_applied` | `true` quando o texto também foi analisado com a ofuscação removida, como caracteres invisíveis ou semelhantes. | | `passes` | O número de perguntas de sim/não respondidas pelo modelo para esta análise. | | `latency_ms` | O tempo que a análise levou, em milissegundos. | | `request_id` | O `request_id` que você enviou ou `null`. | Baseie sua lógica em `decision` e `triggered`. Cada categoria tem seu próprio limite, portanto um único limite de pontuação no seu código não corresponderá ao veredito. ### Categorias Cada resposta pontua o conteúdo em relação a 17 categorias: | Categoria | Abrange | | --------------------------------- | ----------------------------------------------------------------------------------- | | `violent_crimes` | Crimes violentos. | | `sex_related_crimes` | Crimes relacionados a sexo. | | `child_sexual_exploitation` | Exploração sexual infantil. | | `suicide_and_self_harm` | Suicídio e autolesão. | | `indiscriminate_weapons` | Armas químicas, biológicas, radiológicas, nucleares ou explosivas. | | `intellectual_property` | Violação de direitos autorais ou marcas registradas. | | `defamation` | Representação falsa com probabilidade de prejudicar a reputação de uma pessoa real. | | `non_violent_crimes` | Crimes não violentos. | | `hate` | Denegrir pessoas por causa de uma característica protegida. | | `privacy` | Informações privadas e sensíveis sobre uma pessoa. | | `specialized_advice` | Orientação financeira, médica, jurídica ou eleitoral sem as devidas qualificações. | | `sexual_content` | Conteúdo sexualmente explícito ou pornográfico. | | `non_consensual_intimate_imagery` | Despir, desnudar digitalmente ou sexualizar uma pessoa real. | | `minor_coded_language` | Linguagem que indica uma idade sugerindo que o sujeito é menor de idade. | | `real_person_likeness` | A semelhança de uma pessoa real, identificável e nomeada. | | `living_artist_style` | Imitação do estilo característico de um artista vivo específico. | | `prompt_injection` | Uma tentativa de substituir ou manipular as instruções do sistema. | ## Tratando erros Os erros retornam o corpo de erro padrão da Dodo Payments com um `code` e um `message`. Nenhum erro é um veredito, portanto nenhum deles permite a geração: | Status | `code` | Causa | O que fazer | | ------ | ---------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | `400` | `INVALID_REQUEST_PARAMETERS` | A solicitação está malformada ou não contém `text` nem `image`. | Corrija a solicitação. | | `400` | `MODERATION_INVALID_IMAGE` | Não foi possível decodificar a imagem, ela é animada ou pequena demais. | Envie uma imagem estática compatível. | | `403` | `MODERATION_DISABLED` | A Dodo Payments desativou a API de moderação para sua empresa. | Entre em contato com o suporte para saber o motivo. | | `413` | `MODERATION_INPUT_TOO_LARGE` | `text` tem mais de 8.000 caracteres ou `image` excede o limite de tamanho. | Encurte o texto ou reduza a imagem. | | `429` | `MODERATION_OVERLOADED` | A moderação atingiu sua capacidade. Este é um limite de throughput, não um veredito. | Aguarde os segundos indicados no cabeçalho `Retry-After` e tente novamente. | | `503` | `MODERATION_UNAVAILABLE` | Nenhum veredito está disponível. | Não gere conteúdo. Tente novamente mais tarde. | Por padrão, os SDKs tentam novamente duas vezes em caso de `429` ou `503` e aguardam `Retry-After` entre as tentativas. Quando as tentativas terminam, o SDK gera um erro, e seu código deve bloquear a solicitação. ## Testando sua integração O modo de teste retorna vereditos simulados e nunca chama o modelo de moderação, para que você possa testar seu roteamento sem custos. Envie solicitações para `https://test.dodopayments.com` usando uma chave de API do modo de teste. O veredito simulado padrão é `allow`. Para obter outro resultado, coloque uma destas strings em qualquer parte de `text`: | String em `text` | Resposta | | ---------------------- | -------------------------------------------------- | | `dodo_mock_flag` | `200` com `decision` definido como `flag` | | `dodo_mock_deny` | `200` com `decision` definido como `deny` | | `dodo_mock_overloaded` | `429` `MODERATION_OVERLOADED` com `Retry-After: 1` | | `dodo_mock_not_ready` | `503` `MODERATION_UNAVAILABLE` | Um veredito simulado contém uma observação informando que ele é simulado, e todas as pontuações de suas categorias são `0`. O modo de teste aplica a mesma validação de solicitação que o modo live. Para imagens, ele verifica a codificação base64 e o formato, mas não a quantidade de quadros nem as dimensões. Antes de entrar em produção, confirme que sua integração trata cada caso: Envie `dodo_mock_deny` e confirme que seu modelo não é chamado. Envie `dodo_mock_flag` e confirme que seu produto faz o que sua política determina. Envie `dodo_mock_overloaded` e confirme que seu código aguarda `Retry-After` e não gera conteúdo sem um veredito. Envie `dodo_mock_not_ready` e confirme que seu modelo não é chamado. Verifique se todos os caminhos de código que chegam ao seu modelo chamam primeiro a API de moderação. ## Preços e faturamento A API de moderação custa **US\$ 0,30 por 1.000 análises faturáveis**. Não há plano gratuito nem mínimo. Uma análise faturável é uma análise no modo live que retorna um veredito. Estas análises são gratuitas e não são contabilizadas: * Análises no modo de teste. * Análises que retornam um erro, incluindo `429` e `503`. A Dodo Payments fatura em blocos completos de 1.000 análises. Cada bloco completo é cobrado em até uma hora, e as análises que não completam um bloco permanecem sem cobrança até que isso aconteça. A tarifa é debitada do seu saldo em USD e aparece no seu [ledger de saldo](/api-reference/balance-ledger/list-ledger-entries) com o tipo de evento `moderation_fees`. Os pagamentos exibem essa cobrança em **Tarifas de moderação**. ### Acompanhando o uso Para consultar seu uso, chame `GET /moderation/usage`. A resposta retorna: | Campo | Descrição | | ----------------------- | ----------------------------------------------------------------------------------------- | | `unbilled_screens` | Análises faturáveis que a Dodo Payments ainda não cobrou. | | `screens_to_next_block` | Análises faturáveis ainda necessárias para completar o próximo bloco de 1.000. | | `daily` | Suas análises faturáveis por dia UTC nos últimos 30 dias. Dias sem análises são omitidos. | ```bash cURL theme={null} curl https://live.dodopayments.com/moderation/usage \ -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" ``` ```typescript Node.js theme={null} const usage = await client.moderation.retrieveUsage(); console.log(usage.unbilled_screens, usage.screens_to_next_block); ``` ```python Python theme={null} usage = client.moderation.retrieve_usage() print(usage.unbilled_screens, usage.screens_to_next_block) ``` O modo de teste não registra análises, portanto o endpoint de uso não retorna nenhuma atividade do modo de teste. ## Acesso e privacidade A análise exige uma chave de API com acesso de escrita. Qualquer chave de API, incluindo uma chave somente leitura, pode consultar o uso. Consulte [Autenticação](/api-reference/introduction#authentication) para saber como criar uma chave e definir seu nível de acesso. A Dodo Payments não armazena o texto nem as imagens analisados e não os grava em logs. Para cada análise no modo live, ela mantém o horário, o veredito e seu `request_id` para faturamento e relatórios de uso. Cobre seus próprios clientes por cada geração. Venda créditos de geração e desconte-os a cada uso.