OpenRouter Fusion Flash API: stato, configurazione e soluzioni agli errori 400

Chi cerca OpenRouter Fusion Flash API di solito vuole provare il preset Fusion più rapido oppure sta cercando di risolvere un errore HTTP 400. Il punto è che la documentazione ufficiale indica openrouter/fusion-flash, mentre il catalogo live potrebbe non mostrarlo: prima di integrarlo, verifica che l’alias sia effettivamente disponibile nel tuo account.

OpenRouter Fusion Flash è davvero disponibile?

La documentazione ufficiale di Fusion Router elenca openrouter/fusion-flash come slug separato. L’alias viene descritto come Fusion con il preset general-fast selezionato per impostazione predefinita. È pensato per interazioni agentiche più rapide e utilizza un pannello scelto per offrire una latenza più omogenea.

La stessa guida ufficiale spiega che Fusion fa rispondere in parallelo i modelli del pannello, affida a un analista il confronto tra consenso e divergenze e usa poi un modello esterno per scrivere la risposta finale. Fusion Flash è quindi il preset più veloce di questo router composito, non un singolo modello fornito da un provider.

Il catalogo dei modelli OpenRouter consultato per questa guida l’11 settembre 2026 includeva openrouter/fusion, ma non mostrava una voce separata per openrouter/fusion-flash. Un utente ha segnalato esattamente questo problema su X:

“la documentazione dice che openrouter/fusion-flash è un modello elencato separatamente, con una propria voce in /api/v1/models, ma al momento le chiamate API restituiscono un errore 400: fusion-flash non è un model ID valido.” — @PeterDaveHello

Si tratta di una segnalazione di un utente, non di una conferma da parte di OpenRouter. La documentazione ufficiale descrive Fusion, ma nessun annuncio ufficiale individuato per questa guida conferma il lancio o il ritiro separato di Fusion Flash. La conclusione più prudente è: presente nella documentazione, ma da verificare nel catalogo live prima dell’integrazione.

Cosa controllare prima di analizzare il codice

Esegui la richiesta al catalogo dei modelli usando la stessa chiave e lo stesso ambiente dell’applicazione:

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Cerca nel JSON la stringa esatta openrouter/fusion-flash. Non dedurre la disponibilità da una pagina del modello, dall’autocompletamento di un SDK o da un’integrazione memorizzata nella cache. La documentazione sui modelli di OpenRouter considera il catalogo la fonte da consultare per gli identificativi aggiornati e i parametri supportati.

Vale la pena controllare anche la pagina ufficiale dello stato, ma un’infrastruttura indicata come operativa non dimostra che uno specifico alias del router sia utilizzabile in quel momento. Il dashboard riporta componenti generali, come Chat API e Data API: un problema limitato all’alias o alla configurazione può esistere anche mentre la Chat API nel suo complesso funziona regolarmente.

Configurazione minima di OpenRouter Fusion Flash API

Parti dalla richiesta Chat Completions più semplice possibile. In questo modo elimini dal primo test gli adapter degli SDK, gli schemi degli strumenti, lo streaming e le impostazioni Fusion personalizzate.

export OPENROUTER_API_KEY="your-key"

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/fusion-flash",
    "messages": [
      {
        "role": "user",
        "content": "Reply with the word: ready"
      }
    ],
    "stream": false
  }'

Il codice mostra endpoint e intestazioni. Mantieni stream: false nel primo test, così sarà più facile leggere il corpo completo della risposta d’errore.

Se l’alias compare in /api/v1/models e questa richiesta va a buon fine, aggiungi uno alla volta i campi usati dalla tua applicazione. Se invece l’alias non compare, non continuare a modificare i prompt o a ripetere la stessa richiesta. Come test diagnostico, prova l’alternativa documentata:

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/fusion",
    "plugins": [
      {"id": "fusion", "preset": "general-fast"}
    ],
    "messages": [
      {"role": "user", "content": "Reply with the word: ready"}
    ],
    "stream": false
  }'

Questo fallback verifica se il percorso Fusion e il preset veloce sono raggiungibili; non dimostra che alias e configurazione esplicita siano identici sotto ogni aspetto nei backend.

Come isolare gli errori 400 di OpenRouter Fusion Flash API

In genere un 400 indica un rifiuto della richiesta o del provider, ma la causa precisa dipende dal corpo della risposta. È diverso sia da un’interruzione con errore 500 sia da una risposta HTTP 200 che contiene un errore nell’operazione interna di Fusion. Procedi nell’ordine seguente: ogni test deve rispondere a una domanda precisa.

1. Leggi il corpo completo dell’errore

Salva la risposta invece di registrare soltanto 400 Bad Request:

curl -i https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openrouter/fusion-flash","messages":[{"role":"user","content":"ready"}]}'

Cerca codice e messaggio dell’errore, nome del provider, ID della richiesta o della generazione ed eventuali metadati. Il messaggio “fusion-flash is not a valid model ID” fa pensare a una discrepanza nel catalogo o nel rollout. “Provider returned error” indica invece che la richiesta ha raggiunto un percorso del provider, ma è stata rifiutata lì. Se il 400 è generico e privo di dettagli, controlla il record in Activity di OpenRouter invece di procedere per tentativi.

2. Verifica l’ID esatto del modello

Gli identificativi dei modelli sono stringhe sensibili a maiuscole e minuscole. Confronta il valore inviato con la risposta live di /api/v1/models, inclusi punteggiatura e slash. Elimina gli alias obsoleti dalla configurazione e non sostituirli in modo implicito con un nome Gemini o con un altro modello Flash inventato.

Questa matrice diagnostica può aiutare:

Test	Risultato	Prossima azione più probabile
`openrouter/fusion-flash` assente da `/api/v1/models`	Errore 400 o modello non valido	Usa Fusion standard con `general-fast` oppure attendi che l’alias compaia; non considerare la documentazione una prova della disponibilità live.
Alias presente, richiesta minima fallisce	400 prima di introdurre complessità nell’app	Controlla il corpo completo dell’errore e i metadati di Activity; potrebbe trattarsi di un problema dell’account, del router o del rollout.
La richiesta minima funziona, gli strumenti falliscono	400 dopo l’aggiunta degli strumenti	Valida gli schemi degli strumenti e prova con un solo strumento o senza strumenti.
La richiesta minima funziona, lo streaming fallisce	La modalità non-streaming funziona	Verifica separatamente l’adapter di streaming del client e la compatibilità con Fusion.
Fallisce un modello personalizzato del pannello	Le altre configurazioni del pannello funzionano	Rimuovi o sostituisci quel modello e controlla i metadati specifici del provider.
HTTP 200 contiene un errore interno di Fusion	Il trasporto esterno è riuscito	Consideralo un errore interno di pannello o analista, non un 400 di primo livello.

3. Rimuovi i campi non supportati

Invia soltanto model, messages, stream: false e le due intestazioni obbligatorie. Poi reintroduci i campi in questo ordine:

temperature o le impostazioni di reasoning.
plugins e il preset Fusion.
analysis_models personalizzati o model dell’analista.
tools e tool_choice.
Streaming e opzioni della risposta specifiche del framework.

La guida Fusion di OpenRouter documenta analysis_models, model, preset, max_tool_calls, max_completion_tokens, reasoning e temperature. Un campo documentato per un endpoint o una famiglia di modelli non è automaticamente valido per ogni modello upstream. I riferimenti corretti sono la documentazione OpenRouter sui modelli e i metadati dei parametri supportati dal modello.

4. Riduci la complessità degli strumenti e della cronologia

I client con strumenti possono causare errori 400 difficili da interpretare: il payload finale potrebbe contenere uno JSON Schema non valido, un parametro non supportato oppure una sequenza incompleta di messaggi assistant/tool. Una segnalazione pubblica relativa a Hermes Agent ha documentato errori 400 di OpenRouter nella versione 0.10.0 con gli strumenti attivi su diversi modelli testati; il report sospettava i suoi 28 strumenti predefiniti, ma non includeva un controllo riuscito con gli strumenti disattivati né una causa principale confermata. Considera la issue #13927 uno spunto per riprodurre il problema, non la prova che ogni errore 400 di Fusion Flash dipenda dagli strumenti.

Per isolare la causa, prova tutte e tre queste varianti:

Invia lo stesso prompt senza tools.
Invia un solo strumento con uno schema a oggetto semplice.
Avvia una nuova conversazione, senza precedenti chiamate agli strumenti o relativi risultati.

Se la richiesta testuale minima funziona e funziona anche quella con lo strumento ridotto, aggiungi nuovamente gli strumenti uno alla volta. Se una cronologia lunga di utilizzo degli strumenti fallisce mentre una richiesta nuova va a buon fine, accorcia o riassumi la cronologia prima di indagare sul modello.

5. Distingui i problemi di alias, router e provider

Fusion può coinvolgere modelli del pannello, un modello analista e un modello esterno per la risposta. Un errore in una chiamata interna potrebbe quindi non assomigliare a un normale errore di un singolo modello. La documentazione di OpenRouter consiglia di controllare i dati della generazione e quelli di Activity per capire cosa sia stato realmente eseguito. Il campo model della risposta normale può identificare il modello esterno concreto, ma da solo non dimostra che Fusion sia stato usato o escluso.

In un’esecuzione Fusion riuscita, i metadati di generazione documentati includono:

{
  "router": "openrouter/fusion"
}

Se fornisci analysis_models personalizzati, rimuovili e riprova il preset. Se il preset funziona ma un modello personalizzato fallisce, il problema è probabilmente legato ai parametri di quel modello, alla disponibilità del provider o ai limiti di contesto. Se ogni modello fallisce soltanto attraverso un SDK, confronta il payload grezzo dell’SDK con quello cURL funzionante. I client compatibili con OpenAI possono aggiungere strumenti, flag di streaming, formati di risposta o trasformazioni dei messaggi che non risultano visibili nel codice dell’applicazione.

Quando smettere di riprovare

I retry automatici non risolvono un model ID non valido né un rifiuto deterministico dello schema. Se il 400 è marcato come non ripetibile, serve invece un fallback esplicito:

Alias assente dal catalogo: instrada verso openrouter/fusion con general-fast, oppure usa un modello ordinario noto e monitora il catalogo.
Errore 400 legato al payload: conserva la richiesta minima come test di regressione e correggi il primo campo che fa fallire la chiamata.
Errore 400 specifico del provider: rimuovi il modello del pannello interessato o usa un fallback configurato; registra la risposta del provider.
Problema generale della Chat API: controlla la pagina dello stato di OpenRouter e sospendi il rollout invece di modificare la logica dell’applicazione.
HTTP 200 con errore interno: registra i fallimenti dei pannelli e valuta se un risultato parziale sia accettabile; non classificarlo come un errore di autenticazione.

La documentazione ufficiale di Fusion Router stima che il pannello predefinito a tre modelli costi circa 4–5 volte una singola completion; il conto esatto dipende dalle chiamate sottostanti. Un fallback protegge quindi sia l’affidabilità sia la spesa mentre la situazione dell’alias resta incerta.

Domande frequenti su OpenRouter Fusion Flash API

Qual è il model ID corretto di OpenRouter Fusion Flash?

La documentazione ufficiale indica openrouter/fusion-flash. Prima del deployment, verifica quella stringa esatta con GET /api/v1/models, perché documentazione e catalogo live possono divergere temporaneamente.

Fusion Flash è un normale modello veloce?

No. È documentato come Fusion con il preset general-fast. Può comunque effettuare più chiamate interne a modelli diversi: “Flash” descrive l’obiettivo di latenza del preset, non un’esecuzione composta da una sola chiamata.

Quale endpoint devo usare?

Usa https://openrouter.ai/api/v1/chat/completions con autenticazione Bearer e un body JSON. Non inventare un percorso URL specifico per Fusion.

Posso obbligare Fusion a essere eseguito?

La documentazione Fusion supporta tool_choice: "required". Se Fusion è l’unico strumento disponibile, questo di fatto forza una chiamata allo strumento. Se sono presenti altri strumenti, required significa che dovrà essere chiamato uno strumento, non necessariamente Fusion.

Perché la pagina dello stato di OpenRouter può essere verde mentre Fusion Flash restituisce 400?

La pagina dello stato riporta componenti generali del servizio. Un alias mancante, una configurazione non valida del router o un rifiuto specifico del provider possono colpire un singolo percorso mentre la Chat API generale continua a funzionare.

Fusion Flash è gratuito?

Non darlo per scontato. La pagina del modello Fusion di OpenRouter spiega che le completion del pannello e dell’analista contribuiscono al costo anche quando l’alias del router non mostra un prezzo separato per token. Prima di usarlo in produzione, controlla Activity e le tariffe dei modelli selezionati.

Usa il preset veloce solo quando il catalogo live e una richiesta minima danno lo stesso risultato. In caso contrario, passa a Fusion standard o a un modello noto e conserva il payload che fallisce invece di ripetere la richiesta alla cieca.