Rifiuto per policy dei contenuti di HiAPI (CONTENT_POLICY_VIOLATION): cause e soluzioni

Quando invii un'attività di generazione tramite l'interfaccia unificata per attività asincrone di HiAPI, se il prompt o il materiale di input non supera la verifica di sicurezza, ricevi il codice di errore applicativo CONTENT_POLICY_VIOLATION. La documentazione ufficiale ne descrive il significato come «contenuto non conforme alla verifica di sicurezza» e suggerisce come rimedio «modificare il prompt o il contenuto di input e riprovare». Non è un problema di autenticazione, né di saldo o di parametri: è il contenuto stesso a essere stato bloccato. Questo articolo spiega che aspetto ha, dove vederlo e come correggerlo.

1. Sintomi del problema

Il rifiuto per policy dei contenuti si presenta in due forme, a seconda che il blocco avvenga in fase di invio o in fase di esecuzione dell'attività. CONTENT_POLICY_VIOLATION è un codice di errore applicativo dell'interfaccia unificata asincrona e condivide lo stesso insieme di valori con l'error_code sincrono della creazione dell'attività e con data.error.code dello stato finale dell'attività (non è contrassegnato come «solo in fase di creazione», quindi può comparire in entrambi i punti).

Forma A: rifiuto sincrono alla creazione. Quando chiami POST /v1/tasks, il contenuto non supera la verifica e viene restituita una busta di errore con error_code pari a CONTENT_POLICY_VIOLATION. La forma della busta è la seguente (in base alla risposta di errore della documentazione ufficiale, code è lo stato HTTP, error_code è il codice applicativo):

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

In questo caso non ottieni alcun taskId: l'attività non è mai stata creata.

Forma B: stato finale fail dopo l'esecuzione dell'attività. Hai già ottenuto il taskId e l'attività è partita, poi viene giudicata non conforme. Interrogando GET /v1/tasks/{taskId}, l'HTTP resta 200 (il campo message della busta è persino success, che indica solo «questa interrogazione è riuscita», non che la tua attività sia riuscita); il fallimento vero è nascosto in data:

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

Regola di individuazione in una frase: non guardare solo il codice di stato HTTP. Leggi su tre livelli: stato HTTP (la richiesta è stata accettata) → codice di errore applicativo (error_code / data.error.code, perché è stato rifiutato) → stato dell'attività (a che punto è arrivato data.status). Se il campo code (l'error_code della busta sincrona o data.error.code dello stato finale) è CONTENT_POLICY_VIOLATION, si tratta di un blocco della verifica dei contenuti, che non ha nulla a che vedere con timeout, connessioni interrotte o errori di parametri. Il testo di message può variare leggermente a seconda del contesto; il segnale stabile su cui basarsi è questo codice: non fare espressioni regolari sul testo di message.

Quando si attiva lo stesso tipo di blocco nel Playground o nella «prova online» della pagina del modello, la pagina mostra direttamente un avviso in linea «non conforme alla verifica di sicurezza» invece di restituirti il codice da interpretare da solo: è la differenza di presentazione tra il percorso web di prova (sincrono) e il percorso API che usi nel codice.

2. Cause comuni (dalla più probabile alla meno probabile)

1. Il prompt contiene contenuti non consentiti. È il caso più frequente. Contenuti NSFW / per adulti, violenza esplicita e sangue vengono bloccati dalla verifica di sicurezza. Nota che molti modelli di per sé non supportano contenuti NSFW, e alcuni modelli (come GPT Image 2) seguono anche la content policy del fornitore del modello (ad esempio la OpenAI content policy).
2. L'immagine di input / il materiale di riferimento non supera la verifica. Nelle attività image-to-image (i2i) e di generazione video da immagini di riferimento, a essere verificati non sono solo i prompt: anche le immagini caricate o referenziate e i materiali di riferimento devono superare la verifica. Un prompt pulito con un'immagine di input non conforme produce comunque CONTENT_POLICY_VIOLATION.
3. Dopo il cambio di modello si incappa in una policy più severa. Le content policy dei modelli variano in severità. È normale che lo stesso prompt passi con il modello A e venga rifiutato dal modello B, soprattutto in ambiti sensibili come ritratti realistici, volti di personaggi famosi, materiali di brand / protetti da copyright.
4. Scambiare il rifiuto per un altro errore. Un vero blocco dei contenuti viene interpretato come «il servizio fa i capricci» e si riprova più volte con gli stessi contenuti: lo stesso contenuto non passerà mai, per quante volte lo si riprovi, si aspetta solo invano.

3. Passi di correzione

1. Verifica prima il codice di errore. Leggi il codice esatto da error_code della risposta sincrona o da data.error.code dello stato finale dell'attività. Assicurati che sia CONTENT_POLICY_VIOLATION e non TASK_FAILED (fallimento generico, per lo più problemi temporanei o URL delle immagini di input non raggiungibili) o INVALID_REQUEST (corpo della richiesta non valido). Codici diversi richiedono correzioni completamente diverse.
2. Pulisci il prompt voce per voce. Elimina le espressioni NSFW / per adulti, di violenza esplicita e simili, sostituiscile con formulazioni conformi e invia di nuovo. La modifica deve essere mirata, non una cancellazione casuale di parole.
3. Controlla tutti i materiali di input. Nella generazione image-to-image / da riferimento, sostituisci le immagini di input e di riferimento che potrebbero attivare la verifica: anche loro, come il prompt, devono passare la verifica.
4. Verifica la policy del modello di destinazione. Consulta le limitazioni indicate nella pagina del modello (ad esempio la pagina del modello GPT Image 2 specifica «non supporta contenuti NSFW, segue la OpenAI content policy»); se devi cambiare modello, confronta capacità e policy nella vetrina dei modelli.
5. Riprova dopo le modifiche. Il rimedio indicato dalla documentazione per questo codice è «modificare il prompt o il contenuto di input e riprovare». Nota: le attività fallite non vengono addebitate: la quota riservata alla creazione viene restituita per intero quando l'attività raggiunge lo stato finale di fallimento, quindi l'attività bloccata dalla verifica di per sé non costa nulla; ma inviare di nuovo gli stessi contenuti non conformi non passerà: prima modifica, poi invia.

4. Esempio di verifica minima

Per escludere subito «è la mia key / l'accesso a non funzionare», lancia un POST /v1/tasks con un prompt chiaramente conforme e verifica se ottieni regolarmente un taskId (per model usa l'id nudo 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" }
  }'

• Restituisce {"code":200,"data":{"taskId":"tk-hiapi-..."}} → la tua key e l'accesso funzionano; allora il problema della richiesta rifiutata in precedenza è nel contenuto: torna alla sezione 3 e pulisci prompt / immagini di input.
• Restituisce HTTP 401 + {"error":{"code":"permission_denied",...}} → è un problema di autenticazione (key errata / manca Authorization: Bearer), non di policy dei contenuti.
• Anche un prompt conforme restituisce error_code: "CONTENT_POLICY_VIOLATION" → caso piuttosto raro: ricontrolla se in quel prompt ci sono parole sensibili che hai trascurato, o prova con una descrizione più neutra.

5. Letture di approfondimento

• La tabella completa dei codici di errore applicativi dell'interfaccia unificata asincrona (con significato e rimedi di CONTENT_POLICY_VIOLATION, TASK_FAILED, INVALID_REQUEST e altri): documentazione dell'interfaccia unificata asincrona.
• Per confermare le limitazioni sui contenuti di un modello: consulta la pagina del modello corrispondente o la vetrina dei modelli.

6. FAQ

D: Qual è la differenza tra CONTENT_POLICY_VIOLATION e TASK_FAILED? R: Il primo indica che il contenuto non ha superato la verifica di sicurezza; il rimedio è modificare prompt / materiali di input. Il secondo è un fallimento generico, la cui causa più frequente è che l'URL dell'immagine / video di input non è raggiungibile o che c'è una fluttuazione temporanea; il rimedio è correggere l'URL / riprovare. Sono due codici di errore applicativi diversi, non confonderli. Basta leggere error.code per distinguerli.

D: Se un'attività viene rifiutata per policy dei contenuti, mi viene addebitato? R: No. Secondo la documentazione, quando l'attività raggiunge lo stato finale di fallimento, la quota riservata alla creazione viene restituita per intero. Un'attività bloccata dalla verifica non genera costi.

D: Perché con lo stesso prompt la «prova online» web mostra un chiaro avviso «non conforme alla verifica», mentre con l'API ottengo solo un codice? R: La prova web è un percorso sincrono e mostra il risultato della verifica direttamente come avviso in linea; il percorso API mette il risultato in error_code / data.error.code nel corpo della risposta, che il tuo codice deve leggere e gestire con diramazioni. Le informazioni sono le stesse, cambia solo il modo di presentarle.

D: Ho modificato solo il prompt, senza toccare l'immagine di input, perché viene ancora rifiutato? R: La verifica di sicurezza copre i materiali di input, non solo il prompt. Nella generazione image-to-image / da riferimento, sostituisci anche le immagini di input e di riferimento che potrebbero attivare la verifica.

D: HiAPI ha una pagina pubblica di «content policy» consultabile? R: Non c'è una pagina separata di content policy. Le limitazioni sui contenuti dei vari modelli sono indicate nelle rispettive pagine dei modelli (ad esempio «non supporta contenuti NSFW»); per i termini a livello di piattaforma vedi i Termini di servizio e l'Informativa sulla privacy.

D: Riprovando più volte si può «superare per caso»? R: No. Lo stesso contenuto non conforme non passerà mai, per quante volte lo si riprovi: occuperesti solo inutilmente il polling. Modifica prima il contenuto seguendo la sezione 3, poi invia.