Erro "modelo indisponível"/"modelo não encontrado" do hiapi: causas e como corrigir

Se POST https://api.hiapi.ai/v1/tasks rejeitar a requisição porque o modelo está indisponível ou a requisição é inválida, a tarefa não será criada. Antes de tentar novamente, verifique o nome exato do modelo e os campos da requisição na documentação atual do modelo.

Causas comuns

1. O nome do modelo está desatualizado ou incompleto. Nem todos os nomes de modelos do HiAPI seguem o mesmo formato. Alguns são nomes simples, outros incluem o caminho da modalidade. Uma requisição de geração de imagem a partir de texto do GPT Image 2 usa gpt-image-2/text-to-image.
2. Erros de digitação, diferenças de maiúsculas/minúsculas ou espaços ocultos alteraram o nome. Copie o nome do modelo da documentação atual, não digite de memória, e remova os espaços dos valores carregados de variáveis de ambiente.
3. O modelo ou a rota foi desativado ou renomeado. Nomes de artigos antigos ou trechos salvos podem não estar mais disponíveis. Consulte a página atual do modelo e o changelog.
4. A requisição mistura formatos de rota. Quando o modelo oferece várias rotas, use o campo de nível superior route descrito na documentação ou a forma @route suportada, mas não envie valores conflitantes.
5. A autenticação falha antes do roteamento. 401 indica que a chave de API está ausente ou é inválida. 403 indica que a chave não tem permissão. Trate esses casos separadamente dos campos do modelo.

Passos de correção

1. Abra a documentação atual do GPT Image 2 ou a página do modelo relevante e copie o nome exato do modelo.
2. Mantenha o sufixo de modalidade que faz parte do nome na documentação. Para geração de imagem a partir de texto do GPT Image 2, use gpt-image-2/text-to-image.
3. Compare cada campo em input com a tabela de parâmetros desse modelo. Mesmo com um nome de modelo válido, um campo de entrada não suportado ainda pode retornar 400 INVALID_REQUEST.
4. Remova os espaços no ponto da chamada. Em Python, use model = os.environ["MODEL"].strip(); em Node.js, use model.trim().
5. Se o modelo tiver várias rotas, informe o valor de nível superior route descrito na documentação e use a estrutura de parâmetros correspondente a essa rota.
6. Registre o código de status HTTP completo e o corpo da resposta. Não deduza um problema de chave a partir de um erro de validação do modelo, nem um problema de modelo a partir de 401/403.

Valide com uma requisição mínima

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "a small ceramic mug on a wooden table, soft window light",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Um retorno HTTP 200 contendo data.taskId indica que a tarefa foi aceita. Faça polling em GET /v1/tasks/:id até que data.status seja success ou fail, ou configure um callback para produção. Se retornar 400, leia a mensagem de validação e verifique novamente a página do modelo. Se retornar 401 ou 403, corrija a chave ou suas permissões.

Conteúdo relacionado

• Documentação do modelo GPT Image 2
• Referência da API de criação de tarefas
• Guia de autenticação
• Visão geral dos modelos HiAPI

Perguntas frequentes

Devo remover /text-to-image do nome de cada modelo? Não. A nomenclatura dos modelos varia conforme a série. Copie os valores fixos da documentação atual do modelo. Para geração de imagem a partir de texto do GPT Image 2, /text-to-image faz parte do nome do modelo.

Um erro de modelo significa que minha chave está errada? Não necessariamente. A validação da requisição e a autenticação são separadas. 401 indica que a chave está ausente ou é inválida; 403 indica que a chave não tem permissão. 400 aponta para a estrutura da requisição, o nome do modelo, a rota ou os campos de entrada.

Posso normalizar todos os nomes de modelos no cliente? Evite criar suas próprias regras de normalização. Armazene e envie o nome exato publicado na documentação atual do modelo.