Solución al error "Model Not Found" (model_not_found) de la interfaz compatible con OpenAI de HiAPI

Síntoma del problema

Cuando llamas a la interfaz compatible con OpenAI de HiAPI (POST /v1/chat/completions) y el id de model que pasas no lo reconoce HiAPI o no puede enrutarlo, la interfaz devuelve HTTP 400 con el código de error model_not_found en el cuerpo de la respuesta, así:

{
  "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": "..."
  }
}

Ten en cuenta que esto es algo distinto de «un problema con la clave». Si tu API key no es válida o ha caducado, HiAPI devuelve HTTP 401 + permission_denied, y no 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": "..."
  }
}

Si ves permission_denied, primero corrige la key; no te preocupes por el model id. A continuación solo se trata model_not_found.

Causas habituales

Ordenadas de mayor a menor probabilidad de ocurrencia real:

1. El model id tiene un error de escritura o de mayúsculas/minúsculas, o has copiado directamente el slug de la barra de direcciones de la página web. El model id distingue entre mayúsculas y minúsculas y a menudo incluye puntos, guiones y barras (por ejemplo, seedream-5.0-lite, no seedream-5-0-lite). Copiar el slug de la página del modelo desde la barra de direcciones del navegador y usarlo como id es la fuente más frecuente de este error: el slug corto de la URL de la página del modelo no tiene por qué coincidir con el id real de la API.

2. Ese modelo no es en absoluto un modelo de conversación; usa otra interfaz. La mayoría de los modelos de imagen / vídeo / audio de HiAPI solo admiten la interfaz de tareas asíncronas POST /v1/tasks; y los modelos de razonamiento como gpt-5.6 / gpt-6 solo admiten POST /v1/responses. Si los envías a /v1/chat/completions, la interfaz los rechaza con 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 que devuelve GET /v1/models incluye un campo supported_endpoint_types, que es la única referencia sobre «qué interfaz debe usar este modelo» (véase más abajo).

3. El modelo ya no está disponible o ha cambiado de nombre. El id está escrito correctamente, pero ya no aparece en la lista actual de /v1/models: las notas antiguas y los ids antiguos en caché pueden haber quedado obsoletos.

4. Confundir un problema de key / permisos con un problema de modelo. Cuando la clave de la cuenta no es válida se devuelve permission_denied (401), no model_not_found (400). Primero distingue según el código de error de qué tipo se trata y luego corrige lo correspondiente.

Pasos de solución

1. Primero obtén la lista vigente y el id exacto: llama a GET https://api.hiapi.ai/v1/models con tu key. Este es el catálogo en tiempo real y es exactamente lo que el mensaje de error te indica que compruebes; su autoridad prevalece sobre cualquier id codificado en tu código o en tus notas.

2. Fíjate en supported_endpoint_types para determinar la interfaz. Cada entrada de modelo tiene este aspecto:

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

   • task → usa el asíncrono POST /v1/tasks; no puedes usar chat/completions;
   • openai → usa POST /v1/chat/completions (esta es la vía de la que trata este artículo);
   • openai-response → usa POST /v1/responses.

3. Vuelve a enviar la solicitud con el id exacto tal como aparece en la lista. Los modelos multitarea llevan en la lista un sufijo de tipo de tarea (como /text-to-image, /image-to-video); usa el id completo tal como figura en la lista, no solo el slug desnudo de la URL de la página del modelo.

4. Elige bien la interfaz: si es de tipo task, pasa a /v1/tasks; si es de tipo openai-response, pasa a /v1/responses. Cambiar de interfaz resuelve el problema de una vez mejor que probar ids repetidamente en chat/completions.

5. Si el código de error es en realidad permission_denied (401), el problema está en tu key, no en el model id: restablece o cambia la API key por separado.

Ejemplo mínimo de verificación

Para diagnosticar este error, el primer comando es siempre GET /v1/models: no tiene coste ni efectos secundarios y verifica dos cosas de una vez: si la key funciona, si el id existe realmente y qué interfaz debe usarse.

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

• Devuelve 200 + lista de modelos → la key es correcta; a continuación comprueba en la lista el id y su supported_endpoint_types;
• Devuelve 401 + permission_denied → es un problema de la key; corrige primero la key.

Tras confirmar que un modelo es de tipo task, la forma correcta de llamarlo es la interfaz unificada de tareas (el model puede ser el id desnudo, sin el sufijo de tipo de tarea, y también se enruta):

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

Ten en cuenta que /v1/tasks, en cuanto acepta la solicitud, crea realmente una tarea facturable y devuelve un taskId, así que es una «llamada formal tras la corrección», no para probar la conectividad sin más: para una comprobación pura de conectividad usa el GET /v1/models anterior. Si el id no está disponible, el error de /v1/tasks tiene otra estructura plana (distinta de chat/completions):

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

Enlaces internos relacionados

• Documentación de la API Chat Completions —— referencia completa de solicitud / respuesta y comportamiento de errores de la interfaz compatible con OpenAI.
• Documentación general de modelos —— conoce el catálogo de modelos y cómo consultar el id exacto.
• Documentación de la API de creación de tareas —— referencia de los campos model, input y callback de /v1/tasks.
• Mercado de modelos —— explora todos los modelos disponibles.
• Página de precios —— comprueba la disponibilidad de cada modelo y los precios en tiempo real.

FAQ

P: He copiado el id directamente de la URL de la página del modelo, ¿por qué no funciona? R: La URL de la página del modelo suele contener un slug corto, mientras que el id real de la API (especialmente en modelos multitarea) lleva un sufijo de tipo de tarea, por ejemplo gpt-image-2/text-to-image. Toma como referencia el id que devuelve GET /v1/models, no la barra de direcciones del navegador.

P: GET /v1/models/{id} devuelve HTTP 200 para un id que no existe, ¿es un bug? R: No. La interfaz de consulta de un solo modelo devuelve 200 incluso si el id no existe, pero el cuerpo de la respuesta contiene una estructura invalid_request_error / model_not_found en lugar de un código de estado 404/400. Para esta interfaz no mires solo el código de estado HTTP, mira el body. El comportamiento de la interfaz de lista GET /v1/models y de /v1/chat/completions es el descrito arriba.

P: Uso el SDK de OpenAI apuntando a HiAPI y me da model_not_found, ¿es un problema de OpenAI? R: No. Siempre que apuntes el base_url del SDK compatible con OpenAI a HiAPI, la resolución del modelo corre completamente a cargo de HiAPI. model_not_found significa que HiAPI no ha podido hacer coincidir el id que enviaste con un modelo registrado; corrige siguiendo los pasos anteriores.

P: ¿Cómo saber rápidamente qué interfaz debe usar un modelo? R: Fíjate en el supported_endpoint_types de ese modelo en GET /v1/models: si contiene task, usa POST /v1/tasks; si contiene openai, usa POST /v1/chat/completions; si contiene openai-response, usa POST /v1/responses.

P: ¿Los códigos de error de /v1/tasks y /v1/chat/completions son iguales? R: No. /v1/chat/completions usa códigos en minúsculas (como model_not_found, invalid_request) dentro de {"error": {...}}; /v1/tasks usa error_code en mayúsculas (como MODEL_UNAVAILABLE) dentro de una estructura plana {"code","message","data","error_code"}. Al escribir el manejo de errores para ambas interfaces, no asumas que uno sirve para las dos.