HiAPI 400 Bad Request: как исправить ошибки параметров в Task API

Унифицированный асинхронный интерфейс задач возвращает 400 Bad Request, что означает: ваш запрос дошёл до HiAPI, но был отклонён до запуска какой-либо модели — потому что сам JSON или объект input не соответствует схеме данной модели. Ответ выглядит так:

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

Самый полезный字段 — message: он указывает, какой именно параметр и в чём ошибка. 400 — это проблема самого запроса, а не аутентификации или баланса — и поскольку задача вообще не создаётся, отклонённый 400 не тарифицируется.

Что вызывает 400 (от наиболее вероятного к наименее)

Каждый из перечисленных случаев возвращает HTTP 400. При проблемах схемы error_code равен INVALID_REQUEST, при несуществующем id модели — MODEL_UNAVAILABLE. Ниже — реальные тексты ошибок, которые возвращает HiAPI:

Причина	Реальный message, который вы увидите	error_code
Недопустимое значение перечисления	invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'	INVALID_REQUEST
Неверный тип значения	invalid input: prompt: got number, want string	INVALID_REQUEST
Отсутствует обязательное поле / опечатка в имени поля	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
Ошибка формата JSON	invalid json body: unexpected end of JSON input	INVALID_REQUEST
Id модели не существует / с опечаткой	model not available via /v1/tasks	MODEL_UNAVAILABLE

Обратите внимание, что именно проверяет валидатор схемы: значения перечислений (aspect_ratio, resolution и т. п. выходят за пределы допустимого для данной модели набора), типы (там, где нужна строка, передан число, или там, где нужен массив, передан голая строка), имена полей (опечатки вроде promptt, или переименованные, удалённые поля — валидатор одновременно сообщает и о «недостающем обязательном поле», и о «лишнем неизвестном поле»), а также сам id модели (значение не является онлайн-моделью на интерфейсе задач).

Как диагностировать по телу ответа

1. Сначала посмотрите на HTTP-статус. 400 = проблема в вашем запросе. Если вы видите 401, 402, 403, 429 или 504, это другой класс проблем — см. «Связанные материалы» в конце. Если статус на самом деле 401, не пытайтесь исправить его как 400, меняя параметры.
2. Затем посмотрите на error_code. INVALID_REQUEST означает, что тело запроса / input не прошли проверку схемой; MODEL_UNAVAILABLE означает, что значение model не разрешается на /v1/tasks.
3. Прочитайте message дословно. Он привязан к полю: invalid input: <поле>: <причина>. Слово после invalid input: — это и есть параметр, который нужно исправить. Если написано value must be one of ..., допустимые значения напечатаны прямо там — просто скопируйте одно из них.
4. Если видите additional properties '<x>' not allowed, значит вы передали поле, не определённое в схеме данной модели — обычно это опечатка или параметр, скопированный из другой модели. Удалите его или исправьте имя поля.

Об ошибках уровня поля стоит сказать отдельно: многие API изображений и видео на плохой запрос отвечают просто голым 400 Bad Request без каких-либо деталей. HiAPI сверяет ваш input со схемой каждой конкретной модели и сообщает, какое поле и чего от него ожидают — так вы исправляете одно поле за раз, а не гадаете.

Шаги исправления (checklist)

1. Сначала исправьте формат JSON. Если message начинается с invalid json body, значит payload сам по себе не является валидным JSON — проверьте незакрытые фигурные и квадратные скобки, лишние запятые или неэкранированные кавычки. Перед отправкой проверьте строку через jq или python -m json.tool.
2. Убедитесь, что model — это голый онлайн-id. Используйте чистые id вроде z-image, gpt-image-2 — не изобретайте суффиксы маршрутов. Сверьтесь со списком моделей или страницей модели. Несуществующий id вернёт MODEL_UNAVAILABLE.
3. Приведите запрос к схеме модели. Каждая модель объявляет свои поля input. Помещайте параметры генерации в input, а не на верхний уровень. Удалите поля, не перечисленные в схеме (именно они — источник additional properties ... not allowed).
4. Копируйте значения перечислений дословно. Когда message выводит value must be one of ..., скопируйте одно из значений посимвольно (например, "aspect_ratio": "1:1").
5. Передавайте правильные типы. prompt — строка; референсные изображения — в поле-массиве (например, image_urls); числовые поля должны быть числами, а не строками в кавычках. У разных моделей имена полей могут отличаться (например, референсные изображения — input_urls / image_urls / image_input, соотношение сторон — aspect_ratio / ratio / size, длительность может быть строкой или целым числом) — всегда ориентируйтесь на схему данной модели.
6. Отправьте снова и перечитайте. Если снова 400, message на этот раз укажет на следующее поле. Исправляйте по одному, пока вызов не вернёт 200 с taskId.

Минимальный рабочий запрос

Это минимальный корректно оформленный вызов генерации изображения по тексту. Если он возвращает 200 с data.taskId, значит ваш ключ, адрес подключения и структура запроса в порядке — встреченный ранее 400 был проблемой параметров, а не подключения:

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

После успешной отправки data будет содержать taskId. Затем опрашивайте GET https://api.hiapi.ai/v1/tasks/<taskId>, пока data.status не станет success (или fail), после чего читайте результат из data.output. Во время отладки держите запрос минимальным: добавляйте необязательные поля по одному, чтобы новый 400 точно указывал на только что добавленное поле. Полный список полей см. на странице модели, жизненный цикл задачи — в документации API.

Связанные материалы

• Ошибка недействительного API Key: причины, исправление и checklist подключения — читайте, если статус 401, а не 400.
• Исправление «Model Not Found» в HiAPI — про MODEL_UNAVAILABLE и проблемы с id модели.
• Как исправить ошибку ограничения частоты (429) в HiAPI — про троттлинг, а не валидацию запроса.
• Списываются ли средства за неудачные запросы в HiAPI? — о разнице в тарификации между 400 и «сбоем после запуска задачи».
• Страница тарифов и панель управления: проверка кредитов, получение ключа.

FAQ

Что означает error_code: INVALID_REQUEST? Ваше тело запроса или объект input не прошли проверку схемой. Поле message указывает, какой параметр ошибочен. Это не проблема аутентификации (это 401) и не проблема баланса (это 402).

Почему возникает additional properties '<поле>' not allowed? Вы передали поле, не определённое в схеме данной модели — обычно это опечатка (например, prompt написано как promptt), поле, принадлежащее другой модели, или параметр, помещённый на верхний уровень, а не в input. Удалите его или переименуйте.

Списываются ли кредиты за 400 Bad Request? Нет. 400 отклоняется на этапе валидации, задача вообще не создаётся, поэтому и тарифицировать нечего. Списываются только задачи, реально принятые и запущенные.

Я уверен, что JSON правильный, но всё равно 400 — что делать? Прочитайте message дословно. Он привязан к полю и сообщает точный параметр и ожидаемое значение или тип. Если написано value must be one of ..., значит ваше значение не входит в допустимое перечисление — скопируйте одно из разрешённых значений. Если указан тип (got number, want string), исправьте тип.

Это та же ошибка при неверном id модели? Всё ещё HTTP 400, но error_code равен MODEL_UNAVAILABLE, а текст — model not available via /v1/tasks. Используйте голый, актуальный онлайн-id модели, без самодельных суффиксов маршрутов.

Как узнать, какие поля вообще принимает модель? На странице каждой модели перечислены её схема input и пример запроса. Начните с минимального рабочего запроса выше, а затем добавляйте поля по одному, сверяясь с документацией страницы модели.