Geração de imagem

O Hermes Agent gera imagens a partir de texto pela FAL.ai. Onze modelos vêm suportados, cada um com um equilíbrio diferente entre velocidade, qualidade e custo. O modelo ativo é escolhido em hermes tools e fica gravado no config.yaml.

Modelos suportados

Modelo	Velocidade	Pontos fortes	Preço
fal-ai/flux-2/klein/9b (padrão)	menos de 1s	Rápido, texto nítido	US$ 0,006/MP
fal-ai/flux-2-pro	~6s	Fotorrealismo de estúdio	US$ 0,03/MP
fal-ai/z-image/turbo	~2s	Bilíngue inglês e chinês, 6B de parâmetros	US$ 0,005/MP
fal-ai/nano-banana-pro	~8s	Gemini 3 Pro, profundidade de raciocínio, texto	US$ 0,15/imagem (1K)
fal-ai/gpt-image-1.5	~15s	Aderência ao prompt	US$ 0,034/imagem
fal-ai/gpt-image-2	~20s	Texto e caracteres asiáticos no estado da arte, fotorrealismo com noção de mundo	US$ 0,04–0,06/imagem
fal-ai/ideogram/v3	~5s	Melhor tipografia	US$ 0,03–0,09/imagem
fal-ai/recraft/v4/pro/text-to-image	~8s	Design, sistemas de marca, pronto para produção	US$ 0,25/imagem
fal-ai/qwen-image	~12s	Baseado em modelo de linguagem, texto complexo	US$ 0,02/MP
fal-ai/krea/v2/medium/text-to-image	~15 a 25s	Ilustração, anime, pintura, estilos expressivos	US$ 0,030–0,035/imagem
fal-ai/krea/v2/large/text-to-image	~25 a 60s	Fotorrealismo, texturas cruas (desfoque de movimento, grão, filme)	US$ 0,060–0,065/imagem

Os preços são os da FAL no momento da escrita; confira os atuais em fal.ai.

Configuração

Assinantes da Nous

Com uma assinatura paga do Nous Portal, dá para gerar imagem pelo Tool Gateway, sem chave da FAL. A escolha de modelo vale nos dois caminhos. Instalações novas podem rodar hermes setup --portal para autenticar e ligar todas as ferramentas do gateway de uma vez; instalações existentes escolhem Nous Subscription como backend de imagem em hermes tools.

Se o gateway devolver HTTP 4xx para um modelo específico, é porque aquele modelo ainda não passa pelo portal — o agente avisa, com o que fazer (mudar para FAL.ai em hermes tools, com a sua FAL_KEY, ou escolher outro modelo).

Pegar uma chave da FAL

1. Cadastre-se em fal.ai
2. Gere uma chave de API no painel

Configurar e escolher um modelo

hermes tools

Vá em 🎨 Image Generation, escolha o backend (Nous Subscription ou FAL.ai), e o seletor mostra todos os modelos numa tabela alinhada — setas para navegar, Enter para escolher:

  Model                          Speed    Strengths                    Price
  fal-ai/flux-2/klein/9b         <1s      Fast, crisp text             $0.006/MP   ← currently in use
  fal-ai/flux-2-pro              ~6s      Studio photorealism          $0.03/MP
  fal-ai/z-image/turbo           ~2s      Bilingual EN/CN, 6B          $0.005/MP
  ...

A escolha vai para o config.yaml:

image_gen:
  provider: fal                 # `nous` se você escolheu Nous Subscription
  model: fal-ai/flux-2/klein/9b
  max_parallel_requests: 4      # imagens simultâneas numa mesma chamada em lote

O image_gen.provider é a única chave de escolha: nous passa pelo Tool Gateway gerenciado; um nome de fornecedor (fal, openai, xai, krea etc.) vai direto, com a sua chave. O runtime sempre segue essa escolha gravada — uma FAL_KEY no .env é ignorada enquanto o provedor for nous, e provider: fal sem FAL_KEY dá erro (image_gen is configured to use fal (set via hermes tools), but FAL_KEY is not set. Run 'hermes tools' to change it.) em vez de mudar de rota em silêncio. Troque de provedor pelo hermes tools, não acrescentando ou tirando chaves. (O antigo booleano use_gateway é legado — ainda é lido como nous quando true, mas nunca mais é gravado.)

O max_parallel_requests é 4 por padrão. O Hermes o mantém entre um e o limite global de trabalhadores de ferramenta, para os provedores de imagem receberem requisições paralelas limitadas, sem um lote de imagens furar o teto de concorrência do agente.

OpenRouter: o catálogo completo da API de imagem

Com image_gen.provider: openrouter, o seletor lista o catálogo de imagem ao vivo inteiro do OpenRouter — os modelos da API de imagem dedicada (Seedream, FLUX.2, Recraft, Qwen Image, MAI, Krea, Riverflow, Grok Imagine e mais — 40+ identificadores), somados aos modelos de imagem servidos por conversa. O catálogo é buscado ao vivo em GET /images/models e GET /models, então modelos novos aparecem no seletor assim que o OpenRouter os serve; sem precisar atualizar o Hermes. A geração encaminha cada modelo para a superfície que o atende (POST /images/generations dedicado ou conversa) automaticamente. O Nous Portal repassa só o protocolo de conversa, então o seletor dele oferece os modelos servidos por conversa.

Ajustes opcionais por requisição, para modelos da API de imagem, vão na seção de configuração com escopo (ou nas variáveis OPENROUTER_IMAGE_API_*):

image_gen:
  provider: openrouter
  model: bytedance-seed/seedream-4.5
  openrouter:
    resolution: 2K        # depende do modelo: 1K / 2K / 4K
    quality: high         # modelos gpt-image
    output_format: png

Qualidade do GPT-Image

A qualidade dos modelos fal-ai/gpt-image-1.5 e fal-ai/gpt-image-2 é fixada em medium (cerca de US$ 0,034 a 0,06 por imagem em 1024×1024). As camadas low e high não são expostas como opção, para a cobrança do Nous Portal ficar previsível — a diferença de custo entre camadas vai de 3 a 22 vezes. Se você quer mais barato, use o Klein 9B ou o Z-Image Turbo; se quer mais qualidade, use o Nano Banana Pro ou o Recraft V4 Pro.

Uso

O esquema que o agente enxerga é propositalmente mínimo — o modelo usa o que você configurou:

Gere uma imagem de uma paisagem serena de montanha com flores de cerejeira

Crie um retrato quadrado de uma coruja sábia — use o modelo de tipografia

Faça uma cidade futurista, na horizontal

Imagem para imagem, e edição

A mesma ferramenta image_generate também edita imagens existentes, quando o modelo ativo suporta — passe uma imagem de origem e o backend vai para o endpoint de edição sozinho (espelhando o que o video_generate faz com imagem para vídeo). Sem imagem de origem, é geração comum a partir de texto.

Pegue esta foto e transforme numa rua de Tóquio à noite, na chuva → <imagem>

Junte estas duas fotos de produto numa imagem principal → <imagem1> <imagem2>

Duas entradas guiam a edição:

• image_url — a imagem principal a editar (URL pública ou caminho local).
• reference_image_urls — referências extras de estilo e composição (com teto por modelo).

Quais backends editam

Backend	Imagem para imagem	Teto de referências	Como
FAL.ai (nos modelos abaixo)	Sim	até 9	vai para o endpoint /edit do modelo
OpenAI (gpt-image-2)	Sim	até 16	images.edit()
xAI (Grok Imagine)	Sim	1	/v1/images/edits (grok-imagine-image-quality)
Krea (Krea 2)	Sim	até 10	geração guiada por referência (image_style_references)
OpenAI (autenticação Codex)	Sim	até 16	ferramenta image_generation das Responses do Codex, com partes input_image
OpenRouter (modelos da API de imagem)	Sim	14 a 16, por modelo	input_references no POST /images/generations; modelos servidos por conversa usam partes image_url (até 3)

Modelos da FAL com endpoint de edição: flux-2/klein/9b, flux-2-pro, nano-banana-pro, gpt-image-1.5, gpt-image-2, ideogram/v3 e qwen-image. Modelos da FAL que só geram a partir de texto (z-image/turbo, recraft, krea/*) recusam imagem de entrada com um erro claro, apontando um modelo que edita.

A autenticação Codex da OpenAI é por esforço

A superfície do Codex (chatgpt.com/backend-api/codex) oferece o image_generation como uma ferramenta que o modelo de conversa pode chamar, e o Hermes não consegue forçar a chamada — o servidor recusa toda forma de tool_choice para ferramentas hospedadas, então a requisição depende de instrução para convencer o modelo. Quando o modelo se recusa a chamar, o resultado falha com empty_response. Há relatos de que a própria disponibilidade da ferramenta varia de conta para conta. Se você precisa de geração de imagem funcionando de forma determinística, configure o backend da OpenAI (com chave de API), da FAL ou da xAI.

A capacidade de edição do modelo ativo aparece na descrição da ferramenta em tempo de execução, então o agente sabe se o image_url vai ser respeitado antes de chamar.

Proporções

Do ponto de vista do agente, todo modelo aceita as mesmas três proporções. Por dentro, a especificação nativa de cada um é preenchida sozinha:

Entrada do agente	image_size (flux, z-image, qwen, recraft, ideogram)	aspect_ratio (nano-banana-pro)	image_size (gpt-image-1.5)	image_size (gpt-image-2)
landscape	landscape_16_9	16:9	1536x1024	landscape_4_3 (1024×768)
square	square_hd	1:1	1024x1024	square_hd (1024×1024)
portrait	portrait_16_9	9:16	1024x1536	portrait_4_3 (768×1024)

O GPT Image 2 usa presets de 4:3 em vez de 16:9 porque a contagem mínima de pixels dele é 655.360 — o preset landscape_16_9 (1024×576 = 589.824) seria recusado.

Essa tradução acontece no _build_fal_payload() — o código do agente nunca precisa saber das diferenças de esquema entre modelos.

Ampliação

Só quando pedida

Nenhum modelo amplia por padrão. Modelos modernos já entregam a melhor qualidade nativamente, e os ampliadores disponíveis são melhoradores criativos (passadas de difusão) que podem redesenhar o conteúdo sutilmente — estragando texto renderizado, rostos e detalhe fino. A ampliação só roda quando o agente pede.

O parâmetro upscale

• upscale: true — encadeia uma passada de alta resolução depois da geração:

Backend	Ampliador
FAL.ai	Clarity Upscaler (2×, mais US$ 0,03/MP)
Krea	Krea Enhance (2×, teto de 8K)
Outros backends	Sem ampliador; devolve a resolução nativa

• upscale: false, ou omitido — resolução nativa (o padrão)

O video_generate também aceita upscale: true no backend da FAL, encadeando o SeedVR2 da ByteDance (2×, US$ 0,001/MP do vídeo de saída) depois da geração.

Quando a passada de imagem da FAL roda, ela usa:

Ajuste	Valor
Fator de ampliação	2×
Criatividade	0,35
Semelhança	0,6
Escala de orientação	4
Passos de inferência	18

Se a ampliação falhar (rede, limite de requisições), a imagem original é devolvida sozinha. A resposta traz upscaled: true/false, então o agente sabe qual resolução recebeu.

Como funciona por dentro

1. Resolução do modelo — o _resolve_fal_model() lê o image_gen.model do config.yaml, cai na variável FAL_IMAGE_MODEL e depois em fal-ai/flux-2/klein/9b.
2. Montagem do conteúdo — o _build_fal_payload() traduz o seu aspect_ratio para o formato nativo do modelo (preset, proporção ou literal do GPT), junta os parâmetros padrão do modelo, aplica o que quem chamou sobrescreveu, e filtra pela lista supports do modelo, para chaves não suportadas nunca serem enviadas.
3. Envio — o _submit_fal_request() roteia por credenciais diretas da FAL ou pelo gateway gerenciado da Nous, conforme a escolha em image_gen.provider.
4. Ampliação — só quando o agente passou upscale: true; no catálogo, o padrão de todo modelo é desligado.
5. Entrega — a URL final volta ao agente, que emite uma marcação MEDIA:<url>, e os adaptadores de plataforma convertem em mídia nativa.

Depuração

Ligue o log de depuração:

export IMAGE_TOOLS_DEBUG=true

Os logs vão para ./logs/image_tools_debug_<id_da_sessão>.json, com detalhes por chamada (modelo, parâmetros, tempo, erros).

Entrega por plataforma

Plataforma	Entrega
CLI	URL impressa como markdown  — clique para abrir
Telegram	Mensagem de foto, com o prompt na legenda
Discord	Embutida na mensagem
Slack	URL expandida pelo Slack
WhatsApp	Mensagem de mídia
Outras	URL em texto

Limitações

• Exige credencial do backend ativo (FAL_KEY da FAL ou assinatura Nous, OPENAI_API_KEY, OAuth da xAI, KREA_API_KEY)
• Edição depende do modelo — imagem para imagem só funciona nos modelos que editam (tabela acima); os que só geram a partir de texto recusam imagem com um erro claro
• URLs temporárias — os backends devolvem URLs hospedadas, que expiram em horas ou dias; o Hermes materializa no cache local, para a entrega funcionar mesmo depois de expirar
• Restrições por modelo — alguns não suportam seed, num_inference_steps etc. O filtro supports e edit_supports descarta os parâmetros não suportados em silêncio; isso é esperado