HiAPI 400 Bad Request: como corrigir erros de parâmetro na API de tarefas

A interface unificada de tarefas assíncronas retorna 400 Bad Request, o que significa que sua requisição chegou ao HiAPI, mas foi rejeitada antes de qualquer modelo ser executado — porque o próprio JSON ou o objeto input não está em conformidade com o schema desse modelo. A resposta é assim:

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

O campo mais útil é message: ele indica especificamente qual parâmetro está errado e onde está o erro. O 400 é um problema da própria requisição, não de autenticação ou de saldo — e, como nenhuma tarefa foi criada, um 400 rejeitado não é cobrado.

O que dispara um 400 (da maior para a menor probabilidade de ocorrência)

Cada um dos casos abaixo retorna HTTP 400. Para problemas de schema, o error_code é INVALID_REQUEST; quando o id do modelo não existe, é MODEL_UNAVAILABLE. Todos os textos de erro a seguir são retornos reais do HiAPI:

Causa do disparo	O message real que você verá	error_code
Valor de enumeração invá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 errado	invalid input: prompt: got number, want string	INVALID_REQUEST
Campo obrigatório ausente / nome de campo errado	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
Formato JSON inválido	invalid json body: unexpected end of JSON input	INVALID_REQUEST
Id do modelo não existe / digitado errado	model not available via /v1/tasks	MODEL_UNAVAILABLE

Note o que o validador de schema realmente verifica: valores de enumeração (aspect_ratio, resolution etc. fora do conjunto permitido para aquele modelo), tipo (um número onde deveria ir uma string, ou uma string solta onde deveria ir um array), nome do campo (erros de digitação como promptt, ou campos renomeados/removidos — o validador reporta ao mesmo tempo o "campo obrigatório ausente" e o "campo desconhecido adicional") e o próprio id do modelo (valor que não é um modelo online na interface de tarefas).

Como diagnosticar a partir do corpo da resposta

1. Primeiro, olhe o código de status HTTP. 400 = sua requisição tem problema. Se você vê 401, 402, 403, 429 ou 504, é outro tipo de problema — veja "Leitura relacionada" no final. Se o status for na verdade 401, não mexa nos parâmetros achando que é um 400.
2. Depois, olhe o error_code. INVALID_REQUEST indica que o corpo da requisição / input não passou na validação de schema; MODEL_UNAVAILABLE indica que o valor de model não é resolvido em /v1/tasks.
3. Leia o message palavra por palavra. Ele é por campo: invalid input: <campo>: <motivo>. A palavra após invalid input: é o parâmetro a corrigir. Se estiver escrito value must be one of ..., os valores permitidos estão impressos ali — basta copiar um deles exatamente.
4. Se aparecer additional properties '<x>' not allowed, você enviou um campo não definido no schema daquele modelo — normalmente é erro de digitação, ou um parâmetro copiado de outro modelo. Remova-o ou corrija o nome do campo.

Vale destacar essa mensagem por campo: muitas APIs de imagem e vídeo, diante de uma requisição ruim, retornam apenas um 400 Bad Request seco, sem nenhum detalhe. O HiAPI valida seu input contra o schema de cada modelo e informa qual campo é o problema e o que ele espera — assim você corrige um campo de cada vez, em vez de adivinhar.

Passos de correção (checklist)

1. Primeiro corrija o formato JSON. Se o message começa com invalid json body, o payload em si não é JSON válido — verifique chaves e colchetes não fechados, vírgulas extras ou aspas não escapadas. Antes de enviar, valide a string com jq ou python -m json.tool.
2. Confirme que o model é um id online puro. Use ids simples como z-image, gpt-image-2 — não invente sufixos de rota. Confira na lista de modelos ou na página do modelo. Se o id não existir, retorna MODEL_UNAVAILABLE.
3. Alinhe com o schema daquele modelo. Cada modelo declara seus próprios campos de input. Coloque os parâmetros de geração dentro de input, não no nível superior. Remova campos que o schema não lista (é exatamente daí que vem o additional properties ... not allowed).
4. Copie os valores de enumeração exatamente. Quando o message imprime value must be one of ..., copie um dos valores caractere por caractere (por exemplo, "aspect_ratio": "1:1").
5. Envie o tipo correto. prompt é string; imagens de referência vão em campos de array (por exemplo, image_urls); campos numéricos devem ser números, não strings entre aspas. Nomes de campos podem variar entre modelos (por exemplo, imagens de referência usam input_urls / image_urls / image_input, proporção usa aspect_ratio / ratio / size, duração pode ser string ou inteiro) — prevaleça sempre o schema daquele modelo.
6. Reenvie e leia de novo. Se continuar 400, o message desta vez apontará o próximo campo. Corrija um de cada vez, até a chamada retornar 200 com taskId.

Requisição mínima funcional

Esta é a chamada de texto para imagem mínima e corretamente formatada. Se ela retornar 200 com data.taskId, sua key, o endereço de acesso e a estrutura da requisição estão ok — o 400 que você encontrou antes era problema de parâmetros, não de conexão:

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

Após o envio bem-sucedido, data conterá um taskId. Em seguida, consulte GET https://api.hiapi.ai/v1/tasks/<taskId> em polling até data.status virar success (ou fail), e leia o resultado em data.output. Durante a depuração, mantenha a requisição mínima: adicione os campos opcionais um a um, assim qualquer novo 400 aponta exatamente para o campo que você acabou de adicionar. A lista completa de campos está na página do modelo, e o ciclo de vida da tarefa está na documentação da API.

Leitura relacionada

• Erro de API Key inválida: causas, correção e checklist de integração —— leia este se o código de status for 401 em vez de 400.
• Corrigir o "Model Not Found" do HiAPI —— sobre MODEL_UNAVAILABLE e problemas com o id do modelo.
• Como corrigir o erro de limite de requisições (429) do HiAPI —— sobre throttling, não validação de requisição.
• Requisições com falha no HiAPI são cobradas? —— a diferença de cobrança entre um 400 e uma falha "depois que a tarefa começou a rodar".
• Página de preços e painel: consulte créditos e obtenha sua key.

FAQ

O que significa error_code: INVALID_REQUEST? O corpo da sua requisição ou o objeto input não passou na validação de schema. O campo message indica qual parâmetro está errado. Não é problema de autenticação (isso é 401), nem de saldo (isso é 402).

Por que aparece additional properties '<campo>' not allowed? Você enviou um campo não definido no schema daquele modelo — normalmente um erro de digitação (prompt escrito como promptt), um campo de outro modelo, ou um parâmetro colocado no nível superior em vez de dentro de input. Basta remover ou renomear.

Um 400 Bad Request consome créditos? Não. O 400 é rejeitado na fase de validação, nenhuma tarefa é criada e, portanto, não há como cobrar. Apenas tarefas realmente aceitas e executadas são cobradas.

Tenho certeza de que o JSON está correto, mas ainda dá 400. O que fazer? Leia o message palavra por palavra. Ele é por campo e informa o parâmetro exato e o valor ou tipo esperado. Se estiver escrito value must be one of ..., seu valor não está na enumeração permitida — copie exatamente um dos valores permitidos. Se apontar o tipo (got number, want string), corrija o tipo.

Quando o id do modelo está errado, é o mesmo erro? Ainda é HTTP 400, mas o error_code é MODEL_UNAVAILABLE e o texto é model not available via /v1/tasks. Use um id de modelo puro e online no momento, sem sufixos de rota inventados.

Como descobrir quais campos um modelo realmente aceita? A página de cada modelo lista seu schema de input e uma requisição de exemplo. Comece pela requisição mínima funcional acima e vá adicionando os campos um a um conforme a documentação da página do modelo.