Algovate/agnes-image

Agnes 生图

agnes-img é um wrapper do agnes image generate: mesmos parâmetros, com suporte adicional ao modelo 2.5 e fallback automático. Atualmente, o 2.5 (agnes-image-2.5-flash) é o padrão, e o 2.1 (agnes-image-2.1-flash) serve como fallback e compatibilidade.

Verificação prévia

agnes key status

• "status": "missing" significa que a chave não está configurada. Peça ao usuário para acessar https://platform.agnes-ai.com, gerar uma API Key e executar agnes key set <KEY> (salva na configuração local) ou definir a variável de ambiente AGNES_API_KEY.
• Não invente chaves nem as inclua em arquivos do projeto ou no corpo da resposta.

Seleção de modelo

Necessidade	Uso
Padrão (entrega oficial)	Não passar nada → agnes-image-2.5-flash
Especificar 2.1	--model 2.1
Alterar padrão	Variável de ambiente AGNES_IMAGE_MODEL=2.1
Desativar fallback automático	--no-fallback (ou AGNES_IMAGE_FALLBACK=0)

• Prioridade: --model > AGNES_IMAGE_MODEL > padrão 2.5.
• Se o 2.5 retornar erro 5xx, tentará automaticamente com 2.1 uma vez; o stderr exibirá role=fallback; a resposta deve indicar o modelo realmente utilizado.
• O stderr sempre exibirá generated with <model>; use isso para identificar o modelo na resposta.

Texto para imagem

agnes-img --prompt "descrição" --size 2K

• Em caso de sucesso, o stdout contém apenas a URL da imagem; nome do modelo, ID da tarefa, informações de fallback e erros vão para o stderr.
• --size suporta os níveis 1K / 2K / 3K / 4K, além de valores exatos como 1024x768 (padrão 1024x768).
• Por padrão, os níveis são 1:1; para proporções 16:9, 9:16 etc., use as resoluções nativas correspondentes, ex.: 16:9 use 1312x736 (1K) ou 2624x1472 (2K); 9:16 use 736x1312.

Imagem para imagem e composição múltipla

agnes-img --prompt "mude para uma cena cyberpunk noturna" --image ./ref.png
agnes-img --prompt "fusionar estas duas imagens de referência para criar um pôster" --image ./a.png --image ./b.png

• --image pode ser repetido; aceita caminhos locais, URLs públicas ou Data URIs; arquivos locais são automaticamente convertidos para Data URI.
• Ao editar imagens, prompts descrevendo "o que manter, o que mudar" produzem resultados mais estáveis.

Salvar e exibir (obrigatório)

As URLs são temporárias; é necessário baixá-las para a pasta de trabalho:

mkdir -p output output/drafts
curl -sSL "<URL>" -o "output/agnes-$(date +%Y%m%d-%H%M%S).png"
ls -l output/*.png

• Verifique se o arquivo não está vazio (file / tamanho > 0) antes de entregar.
• Use read_image para pré-visualizar a imagem; na resposta, use ![descrição](output/xxx.png) para exibir, ou present conforme necessário.

Convenção de diretórios de saída (obrigatória)

output/                       Imagens de entrega, mantidas permanentemente
  <assunto>.png               Imagem principal do assunto, ex.: eagle-hare.png
  <assunto>-<variante>.png    Outra variante de entrega do mesmo assunto, ex.: eagle-hare-ink.png
output/drafts/                Rascunhos / versões substituídas, podem ser limpos após 7 dias
  <assunto>-<variante>-<YYYYMMDD-HHMM>.png

Regras:

1. Imagens de entrega vão diretamente para output/<assunto>.png; use nomes em minúsculas com hífen, semânticos em inglês, sem sufixos temporários como -v2, -final, -cópia.
2. Imagens antigas substituídas por novas versões, após a nova imagem ser confirmada, mova-as com mv para output/drafts/<assunto>-<timestamp>.png, não as deixe em output/ para evitar confusão.
3. Rascunhos experimentais que não serão entregues (testes de composição, parâmetros) devem ser salvos diretamente em output/drafts/.
4. Para limpeza, use sempre agnes-gc, nunca rm manual de todo o output:

agnes-gc              # Pré-visualização: rascunhos com mais de 7 dias
agnes-gc --apply      # Executa
agnes-gc --all        # Pré-visualização: limpa todos os rascunhos

agnes-gc só atua em diretórios chamados drafts; imagens de entrega em output/ nunca serão removidas por ele.

Perguntas frequentes

• {"ok":false,"error":{"type":"auth",...}}: Chave não configurada ou inválida; primeiro execute agnes key status.
• type: "validation": Parâmetros inválidos (ex.: modelo não suportado, falta --prompt); corrija conforme a hint, não tente novamente cegamente.
• Erro 5xx no modelo 2.5: Haverá fallback automático para 2.1; se o stderr exibir role=fallback, significa que a imagem foi gerada com fallback — informe na entrega.
• Geração normalmente leva de 10 a 60 segundos; defina timeout do Bash de pelo menos 180000 ms.
• Execute apenas uma tarefa de geração por vez para evitar concorrência e estouro de cota.

Notas de compatibilidade

O comando antigo agnes image generate ainda funciona, mas o parâmetro --model só aceita agnes-image-2.1-flash / agnes-image-2.0-flash; não suporta 2.5. Para usar 2.5 ou fallback automático, utilize sempre agnes-img.