Error de "modelo no disponible"/"modelo no encontrado" de hiapi: causas y cómo solucionarlo

Si POST https://api.hiapi.ai/v1/tasks rechaza la solicitud porque el modelo no está disponible o la solicitud no es válida, la tarea no se crea. Antes de reintentar, verifique el nombre exacto del modelo y los campos de la solicitud con la documentación actual de modelos.

Causas habituales

1. El nombre del modelo está obsoleto o incompleto. No todos los nombres de modelo de HiAPI tienen la misma forma. Algunos son nombres sin prefijo y otros incluyen la ruta de la modalidad. Las solicitudes de texto a imagen de GPT Image 2 usan gpt-image-2/text-to-image.
2. Errores de escritura, diferencias de mayúsculas y minúsculas o espacios ocultos alteran el nombre. Copie el nombre del modelo desde la documentación actual en lugar de escribirlo de memoria, y elimine los espacios en blanco de los valores cargados desde variables de entorno.
3. El modelo o la ruta se han desactivado o renombrado. Los nombres de artículos antiguos o fragmentos guardados pueden ya no estar disponibles. Tome como referencia la página de modelos actual y el registro de cambios.
4. La solicitud mezcla formatos de enrutamiento. Cuando el modelo ofrece varias rutas, use el campo de nivel superior route indicado en la documentación o la forma @route admitida, pero no envíe valores contradictorios.
5. La autenticación falla antes del enrutamiento. 401 indica que la clave de API falta o no es válida. 403 indica que la clave no tiene permisos. Trate estos casos por separado de los campos del modelo.

Pasos de corrección

1. Abra la documentación actual de GPT Image 2 o la página del modelo correspondiente y copie el nombre exacto del modelo.
2. Conserve el sufijo de modalidad que forma parte del nombre en la documentación. Para texto a imagen de GPT Image 2, use gpt-image-2/text-to-image.
3. Compare cada campo de input con la tabla de parámetros de ese modelo. Aunque el nombre del modelo sea válido, aún puede devolverse 400 INVALID_REQUEST cuando un campo de entrada no es compatible.
4. Elimine los espacios en blanco en el punto de llamada. En Python, use model = os.environ["MODEL"].strip(); en Node.js, use model.trim().
5. Si el modelo tiene varias rutas, pase el valor de nivel superior route indicado en la documentación y use la estructura de parámetros correspondiente a esa ruta.
6. Registre el código de estado HTTP completo y el cuerpo de la respuesta. No deduzca un problema de clave a partir de un error de validación del modelo, ni un problema de modelo a partir de 401/403.

Verificación con una solicitud 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": "una pequeña taza de cerámica sobre una mesa de madera, luz suave de ventana",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

Un HTTP 200 con data.taskId indica que la tarea se ha aceptado. Consulte GET /v1/tasks/:id hasta que data.status sea success o fail, o configure una devolución de llamada para producción. Si se devuelve 400, lea el mensaje de validación y revise de nuevo la página del modelo. Si se devuelve 401 o 403, corrija la clave o sus permisos.

Contenido relacionado

• Documentación del modelo GPT Image 2
• Referencia de la API para crear tareas
• Guía de autenticación
• Descripción general de los modelos de HiAPI

Preguntas frecuentes

¿Debo eliminar /text-to-image de todos los nombres de modelo? No. La nomenclatura de modelos varía según la serie. Copie los valores fijos de la documentación actual de modelos. Para texto a imagen de GPT Image 2, /text-to-image forma parte del nombre del modelo.

¿Un error de modelo significa que mi clave es incorrecta? No necesariamente. La validación de la solicitud y la autenticación son independientes. 401 indica que la clave falta o no es válida; 403 indica que la clave carece de permisos. 400 apunta a la estructura de la solicitud, el nombre del modelo, la ruta o los campos de entrada.

¿Puedo normalizar todos los nombres de modelo en el cliente? Evite crear sus propias reglas de normalización. Almacene y envíe el nombre exacto publicado en la documentación actual de modelos.