Rejeição por política de conteúdo da HiAPI (CONTENT_POLICY_VIOLATION): causas e correção

Ao enviar uma tarefa de geração na interface unificada de tarefas assíncronas da HiAPI, se o prompt ou o material de entrada não passar na revisão de segurança, você receberá o código de erro de negócio CONTENT_POLICY_VIOLATION, cujo significado na documentação oficial é "conteúdo não passou na revisão de segurança" e cuja recomendação de tratamento é "ajuste o prompt ou o conteúdo de entrada e tente novamente". Não é um problema de autenticação, nem de saldo ou de parâmetros — é o próprio conteúdo que foi bloqueado. Este artigo explica como ele aparece, onde encontrá-lo e como corrigir.

1. Sintomas do problema

A rejeição por política de conteúdo se manifesta de duas formas, dependendo de a interceptação ocorrer na fase de envio ou na fase de execução da tarefa. CONTENT_POLICY_VIOLATION é um código de erro de negócio da interface assíncrona unificada, compartilhando a mesma enumeração do error_code síncrono na criação da tarefa e do data.error.code no estado final da tarefa (ele não está marcado como "apenas no momento da criação", portanto pode aparecer em ambos os lugares).

Forma A: rejeição síncrona na criação. Ao chamar POST /v1/tasks, o conteúdo não passa na revisão e é retornado um envelope de falha com error_code igual a CONTENT_POLICY_VIOLATION. O formato do envelope é o seguinte (conforme a resposta de falha da documentação oficial, code é o status HTTP e error_code é o código de negócio):

{
  "code": 400,
  "message": "...",
  "data": null,
  "error_code": "CONTENT_POLICY_VIOLATION"
}

Nesse caso, não se obtém o taskId — a tarefa simplesmente não foi criada.

Forma B: estado final da tarefa como fail após a execução. Já se obteve o taskId e a tarefa começou a rodar, mas só então foi considerada não conforme. Nesse caso, ao consultar GET /v1/tasks/{taskId}, o HTTP continua sendo 200 (o message do envelope é até success, o que só significa "esta consulta foi bem-sucedida", não que sua tarefa foi bem-sucedida), e a falha real está dentro de data:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-...",
    "status": "fail",
    "error": { "code": "CONTENT_POLICY_VIOLATION", "message": "..." }
  },
  "message": "success"
}

Regra de diagnóstico em uma frase: não olhe apenas o status HTTP. Leia em três camadas — status HTTP (a requisição foi aceita?) → código de erro de negócio (error_code / data.error.code, por que foi rejeitado?) → estado da tarefa (até que etapa o data.status chegou). Sempre que o campo code (o error_code do envelope síncrono ou o data.error.code do estado final) for CONTENT_POLICY_VIOLATION, trata-se de bloqueio pela revisão de conteúdo, e não é a mesma coisa que timeout, conexão interrompida ou erro de parâmetro. O texto de message pode variar ligeiramente conforme o cenário; o sinal estável e verificável é o código, não faça correspondência de texto por regex no message.

Ao acionar esse tipo de bloqueio no Playground / "teste online" da página do modelo, a página exibe diretamente uma mensagem inline de "não passou na revisão de segurança", em vez de entregar o código para você mesmo interpretar — essa é a diferença de apresentação entre o caminho de teste web (síncrono) e o caminho de API que você chama no código.

2. Causas comuns (da maior para a menor probabilidade de ocorrência)

1. O prompt contém conteúdo não permitido. É a mais comum. Conteúdo NSFW / adulto, violência explícita ou sangrenta, entre outros, é bloqueado pela revisão de segurança. Observe que muitos modelos já não suportam conteúdo NSFW, e alguns modelos (como o GPT Image 2) também seguem a política de conteúdo do provedor do modelo (como a política de conteúdo da OpenAI).
2. A imagem de entrada / material de referência não passou na revisão. Em tarefas como imagem para imagem (i2i) e vídeo a partir de imagem de referência, o que passa pela revisão não é só o prompt — as imagens que você envia ou referencia e os materiais de referência também precisam passar. Prompt limpo mas imagem de entrada não conforme continua gerando CONTENT_POLICY_VIOLATION.
3. Ao trocar de modelo, você esbarra em uma política mais rigorosa. A rigidez das políticas de conteúdo varia entre modelos. É normal o mesmo prompt passar no modelo A e ser rejeitado no modelo B, especialmente em direções sensíveis como retratos realistas, retratos de celebridades e materiais de marca / direitos autorais.
4. Confundir a rejeição com outro erro. Uma interceptação real de conteúdo ser tratada como "instabilidade do serviço" e reenviada repetidamente como está — o mesmo conteúdo, não importa quantas vezes seja reenviado, nunca passará, só faz esperar em vão.

3. Passos de correção

1. Primeiro confirme o código de erro. Leia o código exato a partir do error_code da resposta síncrona ou do data.error.code do estado final da tarefa. Confirme que é CONTENT_POLICY_VIOLATION e não TASK_FAILED (falha genérica, geralmente problema transitório ou URL da imagem de entrada inacessível) ou INVALID_REQUEST (corpo da requisição inválido). Códigos diferentes exigem correções completamente diferentes.
2. Limpe o prompt item por item. Remova expressões NSFW / adultas, violência explícita etc. e reenvie com uma redação conforme. A alteração deve ser direcionada, não apenas remover palavras aleatoriamente.
3. Verifique todos os materiais de entrada. Em imagem para imagem / geração com referência, substitua as imagens de entrada e de referência que possam acionar a revisão — elas também precisam passar, assim como o prompt.
4. Verifique a política do modelo alvo. Consulte na página do modelo as restrições indicadas (por exemplo, a página do modelo GPT Image 2 indica explicitamente "não suporta conteúdo NSFW, segue a política de conteúdo da OpenAI"); se precisar trocar de modelo, compare as capacidades e políticas de cada modelo no mercado de modelos.
5. Tente novamente após alterar. A recomendação da documentação para esse código é "ajuste o prompt ou o conteúdo de entrada e tente novamente". Atenção: tarefas com falha não são cobradas — a cota reservada na criação é integralmente devolvida após a tarefa entrar no estado final de falha, portanto a tarefa bloqueada pela revisão em si não custa nada; mas reenviar o mesmo conteúdo violador como está não passará, altere primeiro e depois envie.

4. Exemplo mínimo de verificação

Para primeiro descartar "será que é problema da minha key / integração", dispare um POST /v1/tasks com um prompt claramente conforme e veja se consegue obter o taskId normalmente (model com id puro gpt-image-2):

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": { "prompt": "a cozy coffee shop storefront at sunrise, warm light" }
  }'

• Retorna {"code":200,"data":{"taskId":"tk-hiapi-..."}} → sua key e integração estão funcionando; então a requisição que foi rejeitada anteriormente tem problema no conteúdo, volte à seção 3 para limpar o prompt / imagem de entrada.
• Retorna HTTP 401 + {"error":{"code":"permission_denied",...}} → é problema de autenticação (key incorreta / falta de Authorization: Bearer), não de política de conteúdo.
• Mesmo um prompt conforme retorna error_code: "CONTENT_POLICY_VIOLATION" → é menos comum; reveja se há palavras sensíveis que você ignorou nesse prompt ou tente uma descrição mais neutra.

5. Leitura complementar

• Tabela completa de códigos de erro de negócio da interface assíncrona unificada (incluindo o significado e as recomendações de tratamento de CONTENT_POLICY_VIOLATION, TASK_FAILED, INVALID_REQUEST etc.): documentação da interface assíncrona unificada.
• Para confirmar as restrições de conteúdo de um modelo: consulte a página do modelo correspondente ou o mercado de modelos.

6. FAQ

P: Qual é a diferença entre CONTENT_POLICY_VIOLATION e TASK_FAILED? R: O primeiro indica que o conteúdo não passou na revisão de segurança, e a correção é alterar o prompt / material de entrada; o segundo é uma falha genérica, cuja causa mais comum é URL de imagem / vídeo de entrada inacessível ou flutuação transitória, e a correção é corrigir a URL / tentar novamente. São códigos de erro de negócio diferentes, não os confunda. Basta ler o error.code para distingui-los.

P: Se uma tarefa for rejeitada pela política de conteúdo, serei cobrado? R: Não. Conforme a documentação, após a tarefa entrar no estado final de falha, a cota reservada na criação é integralmente devolvida. A tarefa bloqueada pela revisão em si não gera custo.

P: Para o mesmo prompt, por que no "teste online" da web vejo uma mensagem clara de "não passou na revisão" e pela API recebo apenas um código? R: O teste web é o caminho síncrono e exibe o resultado da revisão diretamente como mensagem inline; o caminho da API coloca o resultado no error_code / data.error.code do corpo da resposta, para o seu código ler e ramificar. A informação é a mesma, só a forma de apresentação difere.

P: Só alterei o prompt, não mexi na imagem de entrada, por que ainda foi rejeitado? R: A revisão de segurança cobre os materiais de entrada, não apenas o prompt. Em imagem para imagem / geração com referência, substitua também as imagens de entrada e de referência que possam acionar a revisão.

P: A HiAPI tem uma página pública de "política de conteúdo" para consultar? R: Não há uma página independente de política de conteúdo. As restrições de conteúdo de cada modelo estão escritas na página do modelo correspondente (por exemplo, "não suporta conteúdo NSFW"); os termos no nível da plataforma estão nos Termos de Serviço e na Política de Privacidade.

P: Reenviar repetidamente pode "passar na sorte"? R: Não. O mesmo conteúdo violador, não importa quantas vezes seja reenviado, nunca passará, apenas consumirá consultas de polling à toa. Altere o conteúdo conforme a seção 3 e então envie.