API OpenRouter Fusion Flash: status, configuração e correção de erros 400

Quem procura pela API OpenRouter Fusion Flash normalmente quer usar o preset rápido do Fusion ou está tentando resolver um erro HTTP 400. O detalhe é que a documentação oficial lista openrouter/fusion-flash, enquanto a descoberta em tempo real pode não mostrar esse alias. Antes de integrar, confirme se ele está disponível na sua conta.

O OpenRouter Fusion Flash está realmente disponível?

A documentação oficial do Fusion Router lista openrouter/fusion-flash como um slug de modelo separado. Segundo o material, esse alias corresponde ao Fusion com o preset general-fast selecionado por padrão. A configuração foi pensada para interações agentic mais rápidas e usa um painel escolhido para oferecer uma latência mais homogênea.

O mesmo guia oficial explica que o Fusion executa os modelos do painel em paralelo, usa um analista para comparar consensos e divergências e, por fim, conta com um modelo externo para redigir a resposta final. O Fusion Flash é o preset mais rápido desse roteador composto — não um modelo de um único provedor.

O catálogo de modelos do OpenRouter consultado para este guia em 11 de setembro de 2026 incluía openrouter/fusion, mas não exibia um registro separado para openrouter/fusion-flash. Um usuário relatou exatamente esse problema no X:

“a documentação diz que openrouter/fusion-flash é um modelo listado separadamente, com sua própria entrada em /api/v1/models, mas as chamadas à API atualmente retornam um erro 400: fusion-flash não é um ID de modelo válido.” — @PeterDaveHello

Esse é um relato de usuário, não uma confirmação do OpenRouter. A documentação oficial descreve o Fusion, mas nenhum anúncio oficial encontrado para este guia confirma um lançamento ou uma retirada separada do Fusion Flash. A conclusão mais segura é: há documentação, mas a disponibilidade em tempo real precisa ser verificada antes da integração.

O que verificar antes de investigar seu código

Faça a requisição ao catálogo de modelos usando a mesma chave e o mesmo ambiente da aplicação:

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

Procure no JSON pela string exata openrouter/fusion-flash. Não conclua que o modelo está disponível com base apenas em uma página de modelo, na lista de autocompletar do SDK ou em uma integração armazenada em cache. A documentação de modelos do OpenRouter trata o catálogo como a fonte dos identificadores atuais e dos parâmetros compatíveis.

A página oficial de status também merece uma consulta, mas o status geral da plataforma estar verde não prova que um alias específico de roteador esteja funcionando. O painel informa componentes amplos, como a Chat API e a Data API. Um problema de alias ou de configuração pode existir enquanto a Chat API continua operacional.

Configuração mínima da API OpenRouter Fusion Flash

Comece com a menor requisição possível para Chat Completions. Assim, você elimina do primeiro teste os adaptadores do SDK, os schemas de ferramentas, o streaming e as configurações personalizadas do Fusion.

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

O exemplo mostra o endpoint e os headers necessários. Mantenha stream: false no primeiro teste para conseguir examinar com mais facilidade o corpo completo do erro.

Se o alias aparecer em /api/v1/models e essa requisição funcionar, acrescente os campos da aplicação um por vez. Se o alias não estiver presente, não adianta continuar alterando prompts ou repetindo a mesma chamada. Como diagnóstico, teste a alternativa documentada:

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

Esse fallback verifica se a rota do Fusion e o preset rápido estão acessíveis. Ele não prova que o alias e a configuração explícita sejam idênticos em todos os detalhes do backend.

Sequência para isolar erros 400 na API OpenRouter Fusion Flash

Um erro 400 geralmente indica uma rejeição da requisição ou do provedor; a causa exata depende do corpo da resposta. É diferente de uma indisponibilidade 500 e também de uma resposta HTTP 200 cuja operação interna do Fusion falhou. Siga esta ordem para que cada teste responda a uma pergunta específica.

1. Leia o corpo completo do erro

Salve a resposta em vez de registrar apenas 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"}]}'

Procure o código e a mensagem de erro, o nome do provedor, o ID da requisição ou da geração e quaisquer metadados. A mensagem “fusion-flash is not a valid model ID” aponta para uma divergência na descoberta ou no rollout. Já “Provider returned error” indica que a requisição chegou a uma rota de provedor, mas foi rejeitada ali. Se o 400 vier sem detalhes úteis, consulte o registro da atividade no OpenRouter em vez de tentar adivinhar.

2. Confirme o ID exato do modelo

Os identificadores de modelo são strings sensíveis a maiúsculas e minúsculas. Compare o valor enviado com a resposta atual de /api/v1/models, incluindo pontuação e a barra. Remova aliases antigos da configuração da aplicação e não substitua silenciosamente o valor por um nome inventado de algum modelo Gemini ou outro modelo Flash.

Uma matriz de diagnóstico útil é:

3. Remova campos incompatíveis

Envie apenas model, messages, stream: false e os dois headers obrigatórios. Depois, reintroduza os campos nesta ordem:

1. temperature ou configurações de raciocínio.
2. plugins e o preset do Fusion.
3. analysis_models personalizado ou model do analista.
4. tools e tool_choice.
5. Streaming e opções de resposta específicas do framework.

O guia do Fusion no OpenRouter documenta analysis_models, model, preset, max_tool_calls, max_completion_tokens, reasoning e temperature. Um campo documentado para um endpoint ou uma família de modelos não é automaticamente válido para todos os modelos upstream. A referência de modelos do OpenRouter e os metadados de parâmetros compatíveis do modelo são as fontes corretas para essa conferência.

4. Simplifique as ferramentas e o histórico de mensagens

Clientes com ferramentas podem causar erros 400 difíceis de interpretar porque o payload final pode conter um JSON Schema inválido, um parâmetro de ferramenta incompatível ou uma sequência incompleta de mensagens assistant/tool. Um relatório público do Hermes Agent documentou falhas 400 no OpenRouter na versão 0.10.0 com ferramentas ativadas em vários modelos testados. O relatório suspeitava das 28 ferramentas padrão, mas não apresentava um controle bem-sucedido com as ferramentas desativadas nem uma causa raiz confirmada. Consulte a issue #13927 como pista de reprodução, não como prova de que todo erro 400 do Fusion Flash seja causado por ferramentas.

Para isolar o problema, tente estas três opções:

• Envie o mesmo prompt sem o campo tools.
• Envie uma única ferramenta com um schema simples de objeto.
• Comece uma conversa nova, sem chamadas anteriores de ferramentas nem resultados de ferramentas.

Se a requisição mínima de texto funcionar e a versão reduzida com ferramentas também, reintroduza as ferramentas individualmente. Se um histórico extenso de uso de ferramentas falhar enquanto uma requisição nova funcionar, reduza ou resuma o histórico antes de investigar o modelo.

5. Separe falhas de alias, roteador e provedor

O Fusion pode envolver modelos do painel, um modelo analista e um modelo responsável pela resposta externa. Uma falha em uma dessas chamadas internas pode não se comportar como a falha de um modelo único. A documentação do OpenRouter recomenda consultar os dados de geração e da Activity para descobrir o que realmente foi executado. O campo model da resposta normal pode identificar o modelo externo concreto, mas sozinho não prova se o Fusion foi ou não usado.

Em uma execução bem-sucedida do Fusion, os metadados de geração documentados incluem:

{
  "router": "openrouter/fusion"
}

Se você informar analysis_models personalizados, remova-os e teste novamente o preset. Se o preset funcionar, mas um modelo personalizado falhar, o problema provavelmente está relacionado aos parâmetros desse modelo, à disponibilidade do provedor ou aos limites de contexto. Se todos os modelos falharem apenas pelo SDK, compare o payload bruto enviado pelo SDK com o payload funcional do cURL. Clientes compatíveis com a API da OpenAI podem acrescentar ferramentas, flags de streaming, formatos de resposta ou transformações de mensagens que não aparecem no código da aplicação.

Quando parar de repetir a requisição

Retries automáticos não resolvem um ID de modelo inválido nem uma rejeição determinística de schema. Quando o 400 for marcado como não reexecutável, crie um caminho de fallback claro:

• Alias ausente na descoberta de modelos: direcione para openrouter/fusion com general-fast ou use um modelo comum conhecido enquanto monitora o catálogo.
• 400 específico do payload: mantenha a requisição mínima como teste de regressão e corrija o primeiro campo que faz a chamada falhar.
• 400 específico do provedor: remova o modelo de painel afetado ou use um fallback configurado; registre a resposta do provedor.
• Incidente amplo na Chat API: consulte a página de status do OpenRouter e pause o rollout em vez de alterar a lógica da aplicação.
• HTTP 200 com falha interna: registre as falhas do painel e decida se um resultado parcial é aceitável; não classifique o caso como falha de autenticação.

A documentação oficial do Fusion Router estima que seu painel padrão de três modelos custe aproximadamente 4 a 5 vezes o preço de uma única conclusão; o valor exato depende das chamadas subjacentes. Um fallback, portanto, protege tanto a confiabilidade quanto os gastos enquanto o alias estiver em uma situação incerta.

FAQ da API OpenRouter Fusion Flash

Qual é o ID correto do modelo OpenRouter Fusion Flash?

A documentação oficial lista openrouter/fusion-flash. Confirme essa string exata em GET /api/v1/models antes da implantação, pois a documentação e a descoberta em tempo real podem divergir temporariamente.

O Fusion Flash é um modelo rápido comum?

Não. Ele é documentado como o Fusion usando o preset general-fast. Ainda assim, pode fazer várias chamadas internas a modelos. Portanto, “Flash” descreve a meta de latência do preset, não uma execução em chamada única.

Qual endpoint devo usar?

Use https://openrouter.ai/api/v1/chat/completions com autenticação Bearer e um corpo JSON. Não invente um caminho de URL específico para o Fusion.

Posso obrigar o Fusion a ser executado?

A documentação do Fusion oferece suporte a tool_choice: "required". Quando o Fusion é a única ferramenta disponível, isso efetivamente força uma chamada de ferramenta. Se houver outras ferramentas, required significa que alguma ferramenta deverá ser chamada — não necessariamente o Fusion.

Por que a página de status do OpenRouter pode estar verde enquanto o Fusion Flash retorna 400?

A página de status informa componentes amplos do serviço. Um alias ausente, uma configuração inválida do roteador ou uma rejeição específica do provedor pode afetar uma rota enquanto a Chat API geral continua operacional.

O Fusion Flash é gratuito?

Não presuma que sim. A página do modelo Fusion do OpenRouter explica que as conclusões do painel e do analista entram na cobrança, mesmo quando o alias do roteador não exibe um preço separado por token. Confira a Activity e as tarifas dos modelos selecionados antes de usar em produção.

Use o preset rápido somente quando a descoberta em tempo real e uma requisição mínima derem o mesmo resultado. Caso contrário, recorra ao Fusion padrão ou a um modelo conhecido e preserve o payload que falhou, em vez de repetir a chamada às cegas.