Risolvere l'errore "Model Not Found" (model_not_found) dell'interfaccia compatibile con OpenAI di HiAPI

Sintomo del problema

Quando chiami l'interfaccia compatibile con OpenAI di HiAPI (POST /v1/chat/completions) e l'id model passato non è riconoscibile o non può essere instradato da HiAPI, l'API restituisce HTTP 400 con il codice di errore model_not_found nel corpo della risposta, così:

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

Nota che questa è una cosa diversa da "problemi con la chiave". Se la tua API key è essa stessa non valida o scaduta, HiAPI restituisce HTTP 401 + permission_denied, non 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 vedi permission_denied, prima sistema la chiave, non preoccuparti del model id. Di seguito parliamo solo di model_not_found.

Cause comuni

In ordine di probabilità effettiva, dalla più alta alla più bassa:

1. Errore di battitura / maiuscole-minuscole nel model id, oppure slug copiato direttamente dalla barra degli indirizzi della pagina web. Il model id è sensibile alle maiuscole-minuscole e spesso contiene punti, trattini, barre (ad esempio seedream-5.0-lite non è seedream-5-0-lite). Copiare lo slug della pagina del modello dalla barra degli indirizzi del browser e usarlo come id è la fonte più comune di questo errore — lo slug breve nell'URL della pagina del modello non è necessariamente uguale al vero id API.

2. Questo modello non è affatto un modello di chat, usa un'altra API. La maggior parte dei modelli di immagini / video / audio su HiAPI supporta solo l'API asincrona di task POST /v1/tasks; i modelli di ragionamento come gpt-5.6 / gpt-6 supportano solo POST /v1/responses. Inviandoli a /v1/chat/completions, l'API li rifiuta 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": "..."
     }
   }
   

   Ogni modello restituito da GET /v1/models porta un campo supported_endpoint_types, che è l'unico criterio per stabilire "quale endpoint usare per questo modello" (vedi sotto).

3. Il modello è stato ritirato o rinominato. L'id è scritto perfettamente, ma non è più nell'elenco corrente di /v1/models — vecchi id in note o cache possono essere scaduti.

4. Problemi di chiave / permessi scambiati per problemi di modello. Quando la chiave dell'account non è valida, l'errore è permission_denied (401), non model_not_found (400). Distingui prima per codice di errore quale categoria è, poi correggi di conseguenza.

Passi di risoluzione

1. Prima ottieni l'elenco attivo e l'id esatto: chiama GET https://api.hiapi.ai/v1/models con la tua chiave. Questo è il catalogo in tempo reale, ed è proprio dove il messaggio di errore ti dice di verificare — la sua autorità è superiore a qualsiasi id hardcoded nel tuo codice o nelle tue note.

2. Guarda supported_endpoint_types per determinare l'endpoint. Ogni voce di modello è così:

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

   • task → usa POST /v1/tasks asincrono, non puoi usare chat/completions;
   • openai → usa POST /v1/chat/completions (è la linea di cui parla questo articolo);
   • openai-response → usa POST /v1/responses.

3. Reinvia la richiesta con l'id esatto così com'è nell'elenco. I modelli multi-task nell'elenco hanno un suffisso del tipo di task (come /text-to-image, /image-to-video); usa l'id completo scritto nell'elenco, non solo lo slug nudo dell'URL della pagina del modello.

4. Scegli l'endpoint corretto: se è di tipo task passa a /v1/tasks, se è di tipo openai-response passa a /v1/responses. Cambiare endpoint risolve in un colpo più di quanto non faccia provare ripetutamente id su chat/completions.

5. Se il codice di errore è in realtà permission_denied (401), il problema è nella tua chiave, non nel model id — vai a resettare o sostituire l'API key separatamente.

Esempio minimo di verifica

Per diagnosticare questo errore, il primo comando è sempre GET /v1/models — è a costo zero, senza effetti collaterali, e verifica due cose in una volta: se la chiave funziona, se l'id esiste davvero, e quale endpoint usare.

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

• Restituisce 200 + elenco modelli → la chiave è valida, poi nell'elenco verifica l'id e il suo supported_endpoint_types;
• Restituisce 401 + permission_denied → è un problema della chiave, prima sistema la chiave.

Dopo aver confermato che un modello è di tipo task, il modo corretto di chiamarlo è l'endpoint unificato dei task (per model basta l'id nudo, anche senza suffisso del tipo di task viene instradato):

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

Nota che /v1/tasks appena accetta la richiesta crea davvero un task a pagamento e restituisce un taskId, quindi è una "chiamata ufficiale dopo la correzione", non serve per testare la connettività a caso — per un controllo puro di connettività usa il GET /v1/models sopra. Se l'id non è disponibile, l'errore di /v1/tasks è un'altra struttura piatta (diversa da chat/completions):

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

Link interni correlati

• Documentazione API Chat Completions —— riferimento completo di richiesta / risposta e comportamento degli errori dell'interfaccia compatibile con OpenAI.
• Documentazione panoramica modelli —— per conoscere il catalogo dei modelli e come trovare l'id esatto.
• Documentazione API creazione task —— riferimento ai campi model, input, callback di /v1/tasks.
• Marketplace dei modelli —— sfoglia tutti i modelli disponibili.
• Pagina prezzi —— verifica la disponibilità e i prezzi in tempo reale di ogni modello.

FAQ

D：Ho copiato l'id direttamente dall'URL della pagina del modello, perché non funziona? R：Nell'URL della pagina del modello c'è spesso uno slug breve, mentre il vero id API (soprattutto per i modelli multi-task) ha un suffisso del tipo di task, ad esempio gpt-image-2/text-to-image. Fai riferimento all'id restituito da GET /v1/models, non alla barra degli indirizzi del browser.

D：GET /v1/models/{id} per un id inesistente restituisce addirittura HTTP 200, è un bug? R：No. L'endpoint di query di singolo modello restituisce 200 anche se l'id non esiste, ma nel corpo della risposta c'è una struttura invalid_request_error / model_not_found, invece di uno status code 404/400. Per questo endpoint non guardare solo lo status code HTTP, guarda il body. L'endpoint di elenco GET /v1/models e /v1/chat/completions si comportano come descritto sopra.

D：Uso l'SDK di OpenAI puntando a HiAPI, ricevo model_not_found, è un problema di OpenAI? R：No. Purché tu punti il base_url dell'SDK compatibile con OpenAI a HiAPI, la risoluzione del modello è completamente a carico di HiAPI. model_not_found significa che HiAPI non è riuscito a far corrispondere l'id che hai passato a un modello registrato, risolvi seguendo i passi sopra.

D：Come capire rapidamente quale endpoint usare per un modello? R：Guarda supported_endpoint_types del modello in GET /v1/models: se contiene task usa POST /v1/tasks, se contiene openai usa POST /v1/chat/completions, se contiene openai-response usa POST /v1/responses.

D：I codici di errore di /v1/tasks e /v1/chat/completions sono uguali? R：No. /v1/chat/completions usa code minuscoli (come model_not_found, invalid_request) racchiusi in {"error": {...}}; /v1/tasks usa error_code maiuscoli (come MODEL_UNAVAILABLE) in un {"code","message","data","error_code"} piatto. Quando scrivi la gestione degli errori per i due endpoint, non dare per scontato che un'unica soluzione vada bene per entrambi.