HiAPI 400 Bad Request: come correggere gli errori di parametro dell'API task

L'interfaccia unificata per le attività asincrone restituisce 400 Bad Request: significa che la tua richiesta ha raggiunto HiAPI ma è stata rifiutata prima che qualsiasi modello venisse eseguito, perché il JSON stesso o l'oggetto input non rispettano lo schema di quel modello. La risposta è così:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'"
}

Il campo più utile è message: indica precisamente quale parametro è sbagliato e in che modo. Un 400 è un problema della richiesta stessa, non di autenticazione o di saldo — e poiché nessuna attività viene creata, un 400 rifiutato non viene addebitato.

Quali casi attivano un 400 (in ordine di probabilità decrescente)

Ognuno dei seguenti casi restituisce HTTP 400. Per i problemi di schema l'error_code è INVALID_REQUEST, mentre quando l'id del modello non esiste è MODEL_UNAVAILABLE. Di seguito i messaggi di errore realmente restituiti da HiAPI:

Causa scatenante	Il message reale che vedrai	error_code
Valore di enumerazione non valido	invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'	INVALID_REQUEST
Tipo di valore errato	invalid input: prompt: got number, want string	INVALID_REQUEST
Campo obbligatorio mancante / nome del campo errato	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
Formato JSON errato	invalid json body: unexpected end of JSON input	INVALID_REQUEST
Id del modello inesistente / scritto male	model not available via /v1/tasks	MODEL_UNAVAILABLE

Nota bene cosa intercetta esattamente il validatore di schema: i valori di enumerazione (valori come aspect_ratio, resolution che escono dall'insieme consentito per quel modello), i tipi (un numero dove serve una stringa, o una stringa nuda dove serve un array), i nomi dei campi (errori di battitura come promptt, oppure campi rinominati o rimossi — il validatore segnala insieme «campo obbligatorio mancante» e «campo sconosciuto in più»), e l'id del modello stesso (il valore non è un modello online sull'interfaccia task).

Come diagnosticare dal corpo della risposta

1. Guarda prima il codice di stato HTTP. 400 = la tua richiesta ha un problema. Se vedi 401, 402, 403, 429 o 504, è un'altra categoria di problema — vedi «Letture correlate» a fine articolo. Se il codice di stato è in realtà 401, non metterti a modificare i parametri come se fosse un 400.
2. Poi guarda l'error_code. INVALID_REQUEST indica che il corpo della richiesta / input non ha superato la validazione dello schema; MODEL_UNAVAILABLE indica che il valore di model non si risolve su /v1/tasks.
3. Leggi il message parola per parola. È a livello di campo: invalid input: <campo>: <motivo>. La parola che segue invalid input: è il parametro da correggere. Se c'è scritto value must be one of ..., i valori consentiti sono elencati lì — basta copiarne uno esattamente.
4. Se trovi additional properties '<x>' not allowed, significa che hai passato un campo non definito nello schema di quel modello — di solito un errore di battitura, oppure un parametro copiato da un altro modello. Eliminalo o correggi il nome del campo.

Questo tipo di errore a livello di campo merita una nota a parte: molte API di immagini e video, di fronte a una richiesta sbagliata, restituiscono solo un misero 400 Bad Request senza alcun dettaglio. HiAPI valida il tuo input contro lo schema specifico di ogni modello e ti dice quale campo è e cosa ci si aspetta — così puoi correggere un campo per volta, invece di tirare a indovinare.

Passi di correzione (checklist)

1. Correggi prima il formato JSON. Se message inizia con invalid json body, il payload stesso non è JSON valido — controlla parentesi graffe e quadre non chiuse, virgole in più o virgolette non sfuggite. Prima di inviare, valida la stringa con jq o python -m json.tool.
2. Verifica che model sia un id online nudo. Usa id puri come z-image, gpt-image-2 — non inventare suffissi di routing. Confronta con la lista dei modelli o la pagina del modello. Un id inesistente restituisce MODEL_UNAVAILABLE.
3. Allineati allo schema di quel modello. Ogni modello dichiara i propri campi input. Metti i parametri di generazione dentro input, non al livello superiore. Elimina i campi non elencati nello schema (è proprio da lì che viene additional properties ... not allowed).
4. Copia esattamente i valori di enumerazione. Quando message stampa value must be one of ..., copia carattere per carattere uno di quei valori (ad esempio "aspect_ratio": "1:1").
5. Passa il tipo giusto. prompt è una stringa; le immagini di riferimento vanno in un campo array (ad esempio image_urls); i campi numerici devono essere numeri, non stringhe tra virgolette. I nomi dei campi possono variare da modello a modello (ad esempio le immagini di riferimento usano input_urls / image_urls / image_input, il rapporto d'aspetto usa aspect_ratio / ratio / size, la durata può essere una stringa o un intero): fai sempre riferimento allo schema di quel modello.
6. Reinvia e rileggi. Se è ancora 400, questa volta message punterà al campo successivo. Correggi un campo per volta finché la chiamata non restituisce 200 con un taskId.

Richiesta minima funzionante

Questa è la chiamata text-to-image minima e corretta. Se restituisce 200 con data.taskId, la tua key, l'endpoint e la struttura della richiesta vanno bene — il 400 che avevi prima era un problema di parametri, non di connessione:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "a red ceramic mug on a wooden table, soft daylight",
      "aspect_ratio": "1:1"
    }
  }'

Dopo l'invio riuscito, data conterrà un taskId. Poi fai polling su GET https://api.hiapi.ai/v1/tasks/<taskId> finché data.status non diventa success (o fail), quindi leggi il risultato da data.output. Durante il debug mantieni la richiesta minima: aggiungi i campi opzionali uno alla volta, così ogni nuovo 400 punta esattamente al campo che hai appena aggiunto. L'elenco completo dei campi è nella pagina del modello, il ciclo di vita delle attività nella documentazione API.

Letture correlate

• Errore API Key non valida: cause, correzioni e checklist di integrazione —— leggi questo se il codice di stato è 401 invece di 400.
• Correggere «Model Not Found» di HiAPI —— per MODEL_UNAVAILABLE e problemi con l'id del modello.
• Come correggere l'errore di rate limit (429) di HiAPI —— per il throttling, non per la validazione della richiesta.
• Le richieste fallite di HiAPI vengono addebitate? —— la differenza di fatturazione tra 400 e «fallimento dopo l'avvio dell'attività».
• Pagina dei prezzi e dashboard: controlla i crediti, ottieni la key.

FAQ

Cosa significa error_code: INVALID_REQUEST? Il corpo della tua richiesta o l'oggetto input non hanno superato la validazione dello schema. Il campo message indica quale parametro è sbagliato. Non è un problema di autenticazione (quello è 401), né di saldo (quello è 402).

Perché compare additional properties '<campo>' not allowed? Hai passato un campo non definito nello schema di quel modello — di solito un errore di battitura (scrivere promptt invece di prompt), un campo appartenente a un altro modello, oppure un parametro messo al livello superiore invece che dentro input. Eliminalo o correggi il nome.

Un 400 Bad Request consuma crediti? No. Un 400 viene rifiutato in fase di validazione, nessuna attività viene creata e quindi non c'è nulla da addebitare. Solo le attività effettivamente accettate ed eseguite vengono addebitate.

Sono sicuro che il JSON sia corretto, ma ricevo ancora 400: cosa faccio? Leggi il message parola per parola. È a livello di campo e ti dice il parametro esatto e il valore o tipo atteso. Se c'è scritto value must be one of ..., il tuo valore non è tra le enumerazioni consentite — copia esattamente un valore consentito. Se invece segnala il tipo (got number, want string), correggi il tipo.

Se sbaglio l'id del modello, l'errore è lo stesso? È sempre HTTP 400, ma l'error_code è MODEL_UNAVAILABLE e il messaggio è model not available via /v1/tasks. Usa un id di modello nudo e attualmente online, senza suffissi di routing inventati.

Come faccio a sapere quali campi accetta davvero un modello? La pagina di ogni modello elenca il suo schema input e una richiesta di esempio. Parti dalla richiesta minima funzionante qui sopra, poi aggiungi i campi uno alla volta seguendo la documentazione della pagina del modello.