Corrigir o erro "Model Not Found" (model_not_found) na interface compatível com OpenAI da HiAPI

Sintoma do problema

Quando você chama a interface compatível com OpenAI da HiAPI (POST /v1/chat/completions) e o model id informado não é reconhecido ou não pode ser roteado pela HiAPI, a interface retorna HTTP 400, com o código de erro model_not_found no corpo da resposta, assim:

{
  "error": {
    "message": "The requested model does not exist or is not available. Check the exact model ID with GET /v1/models and try again. If the issue persists, contact support with request ID: ...",
    "type": "hiapi_error",
    "code": "model_not_found",
    "request_id": "..."
  }
}

Observe que isso é diferente de "problema na chave". Se a sua API key for inválida ou expirada, a HiAPI retorna HTTP 401 + permission_denied, e não model_not_found:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: ...",
    "type": "hiapi_error",
    "request_id": "..."
  }
}

Se aparecer permission_denied, corrija a key primeiro; não se preocupe com o model id. Abaixo tratamos apenas do model_not_found.

Causas comuns

Ordenadas da maior para a menor probabilidade de ocorrência na prática:

1. Erro de grafia / maiúsculas e minúsculas no model id, ou cópia direta do slug da barra de endereços da página web. O model id diferencia maiúsculas de minúsculas e frequentemente contém pontos, hífens e barras (por exemplo, seedream-5.0-lite e não seedream-5-0-lite). Copiar o slug da página do modelo da barra de endereços do navegador e usá-lo como id é a origem mais comum desse erro — o slug curto na URL da página do modelo não necessariamente é igual ao id real da API.

2. Esse modelo simplesmente não é um modelo de chat; ele usa outra interface. A maioria dos modelos de imagem / vídeo / áudio na HiAPI só suporta a interface de tarefas assíncronas POST /v1/tasks; já modelos de raciocínio como gpt-5.6 / gpt-6 só suportam POST /v1/responses. Ao enviá-los para /v1/chat/completions, a interface os rejeita com invalid_request (HTTP 400):

   {
     "error": {
       "message": "The request is incomplete or incorrectly formatted. Please check it and try again...",
       "type": "hiapi_error",
       "param": "",
       "code": "invalid_request",
       "request_id": "..."
     }
   }
   

   Cada modelo retornado por GET /v1/models traz um campo supported_endpoint_types, que é a única base para saber "qual interface esse modelo deve usar" (veja abaixo).

3. O modelo foi descontinuado ou renomeado. A grafia do id está totalmente correta, mas ele não está mais na lista atual de /v1/models — ids antigos em anotações e caches podem estar desatualizados.

4. Confundir problema de key / permissão com problema de model. Quando a chave da conta é inválida, o erro é permission_denied (401), e não model_not_found (400). Primeiro distinga pelo código de erro qual é o tipo, depois corrija o problema certo.

Passos de correção

1. Primeiro obtenha a lista ativa e o id exato: com a sua key, chame GET https://api.hiapi.ai/v1/models. Esse é o catálogo em tempo real e é exatamente onde a mensagem de erro manda você verificar — ele tem mais autoridade do que qualquer id fixo no seu código ou nas suas anotações.

2. Veja supported_endpoint_types para determinar a interface. Cada entrada de modelo é assim:

   { "id": "gpt-image-2/text-to-image", "object": "model", "owned_by": "custom", "supported_endpoint_types": ["task"] }
   

   • task → use o assíncrono POST /v1/tasks, não use chat/completions;
   • openai → use POST /v1/chat/completions (é essa a linha descrita neste artigo);
   • openai-response → use POST /v1/responses.

3. Reenvie a requisição com o id idêntico ao da lista. Modelos multitarefa aparecem na lista com sufixo de tipo de tarefa (como /text-to-image, /image-to-video); use o id completo exatamente como está na lista, não apenas o slug puro da URL da página do modelo.

4. Escolha a interface correta: se for do tipo task, mude para /v1/tasks; se for do tipo openai-response, mude para /v1/responses. Trocar de interface resolve de uma vez, mais do que testar ids repetidamente em chat/completions.

5. Se o código de erro for, na verdade, permission_denied (401), o problema está na sua key, não no model id — redefina ou troque a API key separadamente.

Exemplo mínimo de verificação

Para investigar esse erro, o primeiro comando é sempre GET /v1/models — ele tem custo zero e nenhum efeito colateral, e verifica duas coisas de uma vez: se a key funciona e se o id realmente existe, e qual interface usar.

curl -s https://api.hiapi.ai/v1/models \
  -H "Authorization: Bearer $HIAPI_API_KEY"

• Retornou 200 + lista de modelos → a key está normal; em seguida confira na lista o id e o supported_endpoint_types dele;
• Retornou 401 + permission_denied → é problema de key; corrija a key primeiro.

Depois de confirmar que um modelo é do tipo task, a forma correta de chamada é a interface unificada de tarefas (basta usar o id puro em model; sem o sufixo de tipo de tarefa também é possível rotear):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": { "prompt": "a red apple on a white table" }
  }'

Observe que /v1/tasks, assim que aceita a requisição, realmente cria uma tarefa cobrada e retorna um taskId; portanto, ela é a "chamada oficial após a correção", e não serve para testar conectividade de qualquer jeito — para checagem pura de conectividade, use o GET /v1/models acima. Se o id não estiver disponível, o erro de /v1/tasks tem outra estrutura plana (diferente de chat/completions):

{ "code": 400, "data": null, "error_code": "MODEL_UNAVAILABLE", "message": "model not available via /v1/tasks" }

Links internos relacionados

• Documentação da Chat Completions API —— referência completa de requisição / resposta e comportamento de erros da interface compatível com OpenAI.
• Documentação de visão geral de modelos —— entenda o catálogo de modelos e como consultar o id exato.
• Documentação da API de criação de tarefas —— referência dos campos model, input e callback de /v1/tasks.
• Marketplace de modelos —— navegue por todos os modelos disponíveis.
• Página de preços —— confira se cada modelo está disponível e os preços em tempo real.

FAQ

P: Copiei o id diretamente da URL da página do modelo, por que não funciona? R: A URL da página do modelo costuma ter um slug curto, enquanto o id real da API (especialmente em modelos multitarefa) traz o sufixo do tipo de tarefa, por exemplo gpt-image-2/text-to-image. Use como referência o id retornado por GET /v1/models, e não o que está na barra de endereços do navegador.

P: GET /v1/models/{id} retornou HTTP 200 para um id inexistente, é um bug? R: Não. A interface de consulta de um único modelo retorna 200 mesmo que o id não exista, mas o corpo da resposta é uma estrutura invalid_request_error / model_not_found, e não um status 404/400. Para essa interface, não olhe apenas o status HTTP; olhe o body. Já o comportamento da interface de listagem GET /v1/models e de /v1/chat/completions é o descrito acima.

P: Uso o SDK da OpenAI apontando para a HiAPI e recebo model_not_found; isso é problema da OpenAI? R: Não. Basta apontar o base_url do SDK compatível com OpenAI para a HiAPI e a resolução de modelos passa a ser totalmente responsabilidade da HiAPI. model_not_found significa que a HiAPI não conseguiu corresponder o id que você enviou a nenhum modelo registrado; corrija conforme os passos acima.

P: Como saber rapidamente qual interface um modelo deve usar? R: Veja o supported_endpoint_types do modelo em GET /v1/models: se contém task, use POST /v1/tasks; se contém openai, use POST /v1/chat/completions; se contém openai-response, use POST /v1/responses.

P: Os códigos de erro de /v1/tasks e /v1/chat/completions são iguais? R: Não são. /v1/chat/completions usa codes em minúsculas (como model_not_found, invalid_request) dentro de {"error": {...}}; /v1/tasks usa error_code em maiúsculas (como MODEL_UNAVAILABLE) em um objeto plano {"code","message","data","error_code"}. Ao escrever o tratamento de erros para as duas interfaces, não presuma que um serve para ambas.