HiAPI 400 Bad Request: cómo corregir errores de parámetros en la API de tareas

La interfaz unificada de tareas asíncronas devuelve 400 Bad Request, lo que significa que tu solicitud ya llegó a HiAPI pero fue rechazada antes de que se ejecute cualquier modelo, porque el JSON en sí o el objeto input no cumplen con el schema de ese modelo. La respuesta tiene esta forma:

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

El campo más útil es message: indica específicamente qué parámetro falla y por qué. Un 400 es un problema de la solicitud en sí, no de autenticación ni de saldo; además, como no se creó ninguna tarea, un 400 rechazado no genera cobro.

Qué situaciones provocan un 400 (de mayor a menor probabilidad)

Cada uno de los casos siguientes devuelve HTTP 400. Para problemas de schema, error_code es INVALID_REQUEST; cuando el id del modelo no existe, es MODEL_UNAVAILABLE. Estos son mensajes de error reales devueltos por HiAPI:

Causa	El message real que verás	error_code
Valor de enumeración no válido	invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'	INVALID_REQUEST
Tipo de valor incorrecto	invalid input: prompt: got number, want string	INVALID_REQUEST
Falta un campo obligatorio / nombre de campo mal escrito	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
Error de formato JSON	invalid json body: unexpected end of JSON input	INVALID_REQUEST
El id del modelo no existe / está mal escrito	model not available via /v1/tasks	MODEL_UNAVAILABLE

Fíjate en qué detecta realmente el validador de schema: valores de enumeración (aspect_ratio, resolution y otros valores fuera del conjunto permitido para ese modelo), tipos (un número donde se espera una cadena, o una cadena suelta donde se espera un array), nombres de campo (erratas como promptt, o campos renombrados o eliminados; el validador informa a la vez del «campo obligatorio faltante» y de la «propiedad adicional desconocida») y el propio id del modelo (cuyo valor no es un modelo en línea de la interfaz de tareas).

Cómo diagnosticar a partir del cuerpo de la respuesta

1. Primero mira el código de estado HTTP. 400 = tu solicitud tiene un problema. Si ves 401, 402, 403, 429 o 504, es otro tipo de problema; consulta «Lecturas relacionadas» al final. Si el código de estado es en realidad 401, no cambies parámetros tratándolo como un 400.
2. Luego mira error_code. INVALID_REQUEST indica que el cuerpo de la solicitud / input no pasó la validación de schema; MODEL_UNAVAILABLE indica que el valor de model no se resuelve en /v1/tasks.
3. Lee message al pie de la letra. Es a nivel de campo: invalid input: <campo>: <motivo>. La palabra después de invalid input: es el parámetro que debes corregir. Si dice value must be one of ..., los valores permitidos están ahí mismo; copia uno tal cual.
4. Si aparece additional properties '<x>' not allowed, significa que enviaste un campo que el schema de ese modelo no define, normalmente una errata o un parámetro copiado de otro modelo. Elimínalo o cámbialo por el nombre de campo correcto.

Vale la pena detenerse en este tipo de error a nivel de campo: muchas API de imagen y vídeo, ante una solicitud incorrecta, solo devuelven un escueto 400 Bad Request sin ningún detalle. HiAPI valida tu input contra el schema específico de cada modelo y te dice qué campo es y qué se espera, de modo que puedes corregir un campo correctamente de una vez en lugar de adivinar.

Pasos de corrección (checklist)

1. Corrige primero el formato JSON. Si message empieza por invalid json body, el payload en sí no es JSON válido; revisa llaves o corchetes sin cerrar, comas sobrantes o comillas sin escapar. Antes de enviar, valida la cadena con jq o python -m json.tool.
2. Confirma que model es un id en línea sin adornos. Usa ids puros como z-image o gpt-image-2; no inventes sufijos de ruta. Compruébalo con la lista de modelos o la página del modelo. Si el id no existe, devolverá MODEL_UNAVAILABLE.
3. Alinea con el schema de ese modelo. Cada modelo declara sus propios campos de input. Coloca los parámetros de generación dentro de input, no en el nivel superior. Elimina los campos que el schema no enumera (de ahí viene additional properties ... not allowed).
4. Copia los valores de enumeración tal cual. Cuando message muestre value must be one of ..., copia carácter por carácter uno de esos valores (por ejemplo, "aspect_ratio": "1:1").
5. Usa el tipo correcto. prompt es una cadena; las imágenes de referencia van en un campo de tipo array (por ejemplo, image_urls); los campos numéricos deben ser números, no cadenas entre comillas. Los nombres de campo pueden variar entre modelos (por ejemplo, las imágenes de referencia usan input_urls / image_urls / image_input, la relación de aspecto usa aspect_ratio / ratio / size, y la duración puede ser cadena o entero); guíate siempre por el schema de ese modelo.
6. Reenvía y vuelve a leer. Si sigue dando 400, esta vez message apuntará al siguiente campo. Corrige de uno en uno hasta que la llamada devuelva 200 con un taskId.

Solicitud mínima funcional

Esta es la llamada de texto a imagen más pequeña y con formato correcto. Si devuelve 200 con data.taskId, tu key, la dirección de acceso y la estructura de la solicitud están bien; el 400 que encontrabas antes era un problema de parámetros, no de conexión:

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

Tras un envío correcto, data incluirá un taskId. Después consulta repetidamente GET https://api.hiapi.ai/v1/tasks/<taskId> hasta que data.status pase a success (o fail), y lee el resultado desde data.output. Durante la depuración, mantén la solicitud lo más mínima posible: vuelve a añadir los campos opcionales uno a uno, así cada nuevo 400 apuntará exactamente al campo que acabas de añadir. Para la lista completa de campos, consulta la página del modelo; para el ciclo de vida de la tarea, consulta la documentación de la API.

Lecturas relacionadas

• Error de API Key no válida: causas, solución y checklist de integración: consulta esto cuando el código de estado sea 401 y no 400.
• Corregir el «Model Not Found» de HiAPI: sobre MODEL_UNAVAILABLE y problemas con el id del modelo.
• Cómo corregir el error de límite de tasa (429) de HiAPI: sobre la limitación de peticiones, no sobre la validación de la solicitud.
• ¿HiAPI cobra por solicitudes fallidas?: la diferencia de facturación entre un 400 y un fallo «después de que la tarea se haya ejecutado».
• Página de precios y panel de control: consulta créditos y obtén tu key.

FAQ

¿Qué significa error_code: INVALID_REQUEST? Que el cuerpo de tu solicitud o el objeto input no pasaron la validación de schema. El campo message señala qué parámetro falla. No es un problema de autenticación (eso es 401) ni de saldo (eso es 402).

¿Por qué aparece additional properties '<campo>' not allowed? Enviaste un campo que el schema de ese modelo no define, normalmente una errata (escribir prompt como promptt), un campo que pertenece a otro modelo, o un parámetro colocado en el nivel superior en lugar de dentro de input. Elimínalo o cámbialo de nombre.

¿400 Bad Request descuenta créditos? No. Un 400 se rechaza en la fase de validación, no se creó ninguna tarea y no hay nada que facturar. Solo se cobran las tareas que realmente se aceptan y se ejecutan.

Estoy seguro de que el JSON es correcto, pero sigo recibiendo 400. ¿Qué hago? Lee message al pie de la letra. Es a nivel de campo y te dirá el parámetro exacto y el valor o tipo esperado. Si dice value must be one of ..., tu valor no está entre las enumeraciones permitidas; copia tal cual uno de los valores permitidos. Si apunta al tipo (got number, want string), corrige el tipo.

¿Es el mismo error cuando el id del modelo está mal escrito? Sigue siendo HTTP 400, pero error_code es MODEL_UNAVAILABLE y el mensaje es model not available via /v1/tasks. Usa el id puro y actualmente en línea del modelo, sin sufijos de ruta inventados.

¿Cómo saber qué campos acepta exactamente un modelo? La página de cada modelo enumera su schema de input y una solicitud de ejemplo. Empieza con la solicitud mínima funcional de arriba y ve añadiendo los campos uno a uno según la documentación de la página del modelo.