HiAPI 400 Bad Request : comment corriger les erreurs de paramètres de l'API de tâches

L'interface de tâches asynchrones unifiée renvoie 400 Bad Request, ce qui signifie que votre requête a bien atteint HiAPI, mais qu'elle a été rejetée avant l'exécution de tout modèle — parce que le JSON lui-même ou l'objet input ne respecte pas le schéma de ce modèle. La réponse ressemble à ceci :

{
  "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'"
}

Le champ le plus utile est message : il indique précisément quel paramètre pose problème et pourquoi. Un 400 est un problème lié à la requête elle-même, pas à l'authentification ni au solde — et comme aucune tâche n'a été créée, un 400 rejeté n'est jamais facturé.

Quels cas déclenchent un 400 (par ordre de probabilité décroissante)

Chacun des cas ci-dessous renvoie un HTTP 400. Pour les problèmes de schéma, error_code vaut INVALID_REQUEST ; lorsque l'id de modèle n'existe pas, il vaut MODEL_UNAVAILABLE. Voici les messages d'erreur réellement renvoyés par HiAPI :

Cause	Le message réel que vous verrez	error_code
Valeur d'énumération invalide	invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'	INVALID_REQUEST
Type de valeur incorrect	invalid input: prompt: got number, want string	INVALID_REQUEST
Champ obligatoire manquant / nom de champ mal orthographié	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
JSON mal formé	invalid json body: unexpected end of JSON input	INVALID_REQUEST
Id de modèle inexistant / mal orthographié	model not available via /v1/tasks	MODEL_UNAVAILABLE

Notez ce que le validateur de schéma vérifie réellement : les valeurs d'énumération (aspect_ratio, resolution, etc. dont la valeur sort de l'ensemble autorisé pour ce modèle), les types (un nombre là où il faut une chaîne, ou une chaîne brute là où il faut un tableau), les noms de champs (une faute de frappe comme promptt, ou un champ renommé ou supprimé — le validateur signale à la fois le « champ obligatoire manquant » et le « champ inconnu superflu »), ainsi que l'id de modèle lui-même (dont la valeur ne correspond pas à un modèle en ligne sur l'interface de tâches).

Comment diagnostiquer à partir du corps de la réponse

1. Regardez d'abord le code de statut HTTP. 400 = votre requête pose problème. Si vous voyez 401, 402, 403, 429 ou 504, il s'agit d'un autre type de problème — voir « À lire également » en fin d'article. Si le code de statut est en réalité 401, ne modifiez pas les paramètres comme s'il s'agissait d'un 400.
2. Regardez ensuite error_code. INVALID_REQUEST signifie que le corps de requête / input n'a pas passé la validation de schéma ; MODEL_UNAVAILABLE signifie que la valeur de model ne se résout pas sur /v1/tasks.
3. Lisez message mot pour mot. Il est au niveau du champ : invalid input: <champ>: <raison>. Le mot qui suit invalid input: est le paramètre à corriger. S'il est écrit value must be one of ..., les valeurs autorisées sont imprimées juste là — il suffit d'en recopier une à l'identique.
4. Si vous voyez additional properties '<x>' not allowed, cela signifie que vous avez envoyé un champ non défini par le schéma de ce modèle — souvent une faute de frappe, ou un paramètre copié depuis un autre modèle. Supprimez-le, ou remplacez-le par le bon nom de champ.

Ce type d'erreur au niveau du champ mérite une mention spéciale : beaucoup d'API d'image et de vidéo se contentent de renvoyer un 400 Bad Request tout nu face à une requête erronée, sans aucun détail. HiAPI valide votre input par rapport au schéma propre à chaque modèle et vous indique quel champ pose problème et ce qui est attendu — vous pouvez ainsi corriger un champ à la fois, au lieu de deviner.

Étapes de correction (checklist)

1. Corrigez d'abord le format JSON. Si message commence par invalid json body, le payload lui-même n'est pas un JSON valide — vérifiez les accolades ou crochets non fermés, les virgules superflues, ou les guillemets non échappés. Validez la chaîne avec jq ou python -m json.tool avant l'envoi.
2. Vérifiez que model est un id en ligne brut. Utilisez un id pur comme z-image ou gpt-image-2 — n'inventez pas de suffixes de routage. Vérifiez par rapport à la liste des modèles ou à la page du modèle. Un id inexistant renvoie MODEL_UNAVAILABLE.
3. Alignez-vous sur le schéma du modèle. Chaque modèle déclare ses propres champs input. Placez les paramètres de génération dans input, pas au niveau supérieur. Supprimez les champs non listés dans le schéma (c'est justement la source de additional properties ... not allowed).
4. Recopiez les valeurs d'énumération à l'identique. Lorsque message affiche value must be one of ..., recopiez caractère par caractère l'une des valeurs (par exemple "aspect_ratio": "1:1").
5. Envoyez le bon type. prompt est une chaîne ; les images de référence vont dans un champ tableau (par exemple image_urls) ; les champs numériques doivent être des nombres, pas des chaînes entre guillemets. Les noms de champs peuvent différer selon les modèles (par exemple les images de référence avec input_urls / image_urls / image_input, le format avec aspect_ratio / ratio / size, la durée qui peut être une chaîne ou un entier), référez-vous toujours au schéma de ce modèle.
6. Renvoyez et relisez. Si c'est encore un 400, message pointera cette fois vers le champ suivant. Corrigez-en un à la fois, jusqu'à ce que l'appel renvoie un 200 avec un taskId.

Requête minimale fonctionnelle

Voici l'appel texte-vers-image minimal et correctement formaté. S'il renvoie un 200 avec data.taskId, cela signifie que votre clé, votre point d'accès et la structure de votre requête sont corrects — le 400 que vous rencontriez était un problème de paramètres, pas de connexion :

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"
    }
  }'

Après une soumission réussie, data contiendra un taskId. Interrogez ensuite GET https://api.hiapi.ai/v1/tasks/<taskId> jusqu'à ce que data.status passe à success (ou fail), puis lisez le résultat dans data.output. Pendant le débogage, gardez la requête minimale : rajoutez les champs optionnels un par un, afin que tout nouveau 400 pointe précisément vers le champ que vous venez d'ajouter. La liste complète des champs se trouve sur la page du modèle, et le cycle de vie des tâches dans la documentation de l'API.

À lire également

• Erreur de clé API invalide : causes, corrections et checklist d'intégration —— à consulter lorsque le code de statut est 401 et non 400.
• Corriger le « Model Not Found » de HiAPI —— pour les problèmes de MODEL_UNAVAILABLE et d'id de modèle.
• Comment corriger l'erreur de limitation de débit (429) de HiAPI —— pour la limitation de débit, et non la validation de requête.
• Les requêtes HiAPI échouées sont-elles facturées ? —— la différence de facturation entre un 400 et un échec « après démarrage de la tâche ».
• Page de tarifs et tableau de bord : consultez vos crédits, récupérez votre clé.

FAQ

Que signifie error_code: INVALID_REQUEST ? Votre corps de requête ou objet input n'a pas passé la validation de schéma. Le champ message nomme le paramètre en cause. Ce n'est pas un problème d'authentification (c'est 401), ni un problème de solde (c'est 402).

Pourquoi additional properties '<champ>' not allowed apparaît-il ? Vous avez envoyé un champ non défini par le schéma de ce modèle — souvent une faute de frappe (promptt au lieu de prompt), un champ appartenant à un autre modèle, ou un paramètre placé au niveau supérieur au lieu de input. Supprimez-le ou renommez-le.

Un 400 Bad Request consomme-t-il des crédits ? Non. Un 400 est rejeté à l'étape de validation, aucune tâche n'a été créée, il n'y a donc rien à facturer. Seules les tâches réellement acceptées et exécutées sont facturées.

Je suis sûr que mon JSON est correct, mais j'obtiens quand même un 400, que faire ? Lisez message mot pour mot. Il est au niveau du champ et vous indiquera le paramètre exact et la valeur ou le type attendu. S'il est écrit value must be one of ..., votre valeur n'est pas dans l'énumération autorisée — recopiez une valeur autorisée à l'identique. Si c'est le type qui est pointé (got number, want string), corrigez le type.

L'erreur est-elle identique lorsque l'id de modèle est faux ? C'est toujours un HTTP 400, mais error_code vaut MODEL_UNAVAILABLE, avec le message model not available via /v1/tasks. Utilisez un id de modèle brut et actuellement en ligne, sans suffixe de routage inventé.

Comment savoir quels champs un modèle accepte exactement ? La page de chaque modèle liste son schéma input et un exemple de requête. Partez de la requête minimale fonctionnelle ci-dessus, puis ajoutez les champs un par un en suivant la documentation de la page du modèle.