Habilidade de Geração Multimodal Agnes AI

Visão Geral

Esta Skill encapsula todas as capacidades de geração da Agnes AI (Sapiens AI), invocadas de forma unificada através de um script CLI:

Geração de Texto: agnes-2.5-flash (suporta modo de raciocínio Thinking, $0)
Compreensão de Imagem/Vision: agnes-2.5-flash (compatível com OpenAI Vision API, pode analisar conteúdo de imagem)
Texto para Imagem/Imagem para Imagem: agnes-image-2.5-flash (mais recente, otimizado para alta densidade de informação; use --model agnes-image-2.1-flash para retroceder para a geração anterior)
Mecanismo de Vídeo Um (V2.0): agnes-video-v2.0 — texto para vídeo / imagem para vídeo / animação de quadros-chave, taxa de quadros e resolução livres, $0/segundo
Mecanismo de Vídeo Dois (Video 2.5 Flash): agnes-video-2.5-flash — novo modelo, três modos: texto/quadro-chave/referência, referência multimodal, 720P gratuito por tempo limitado; upgrade pago --model agnes-video-2.5 desbloqueia 960P/2K e referência de vídeo
Tradução Automática: prompts em chinês são automaticamente traduzidos para inglês antes de chamar a API
Polling Assíncrono: tarefas de vídeo fazem polling automaticamente até a conclusão

Pré-requisitos

Confirme que a Chave da API está configurada:
- Lê preferencialmente a API_KEY codificada em scripts/agnes_client.py
- Se for um placeholder YOUR_AGNES_API_KEY_HERE, recai para a variável de ambiente AGNES_API_KEY
- Se nenhuma estiver configurada, lembre o usuário de definir a Chave da API no código ou na variável de ambiente
Python 3.8+, bibliotecas padrão urllib + json são suficientes, sem dependências adicionais.

Referência Rápida de Comandos CLI

Localização do script: scripts/agnes_client.py

# Geração de texto
python scripts/agnes_client.py text "Seu prompt"
python scripts/agnes_client.py text "Olá" --stream
python scripts/agnes_client.py text "Escreva um quicksort para mim" --thinking  # Modo de raciocínio 2.5

# Texto para imagem (agnes-image-2.5-flash, padrão 1K; formato recomendado tamanho + proporção)
python scripts/agnes_client.py image "Uma cidade futurista ao pôr do sol, realismo cinematográfico" --size 2K --ratio 16:9
python scripts/agnes_client.py image "Um gato passeando ao luar"
python scripts/agnes_client.py image "..." --model agnes-image-2.1-flash   # Retroceder para geração anterior

# Imagem para imagem (detecção automática de proporção — padrão baseado na proporção da imagem de referência principal)
python scripts/agnes_client.py image "Transformar para noite cyberpunk" --image-url "https://...input.png" --image-url "https://...ref.png"

# Imagem para imagem + proporção especificada manualmente (sem detecção automática)
python scripts/agnes_client.py image "Transformar para noite cyberpunk" --image-url "https://...input.png" --ratio 16:9

# ── Mecanismo de Vídeo Um: V2.0 (taxa de quadros/resolução livres, $0) ──
python scripts/agnes_client.py video "Um drone voando sobre montanhas ao nascer do sol" --poll          # Texto para vídeo
python scripts/agnes_client.py video "Adicionar movimento a esta cena" --image-url "https://...frame.png" --poll  # Imagem para vídeo
python scripts/agnes_client.py video --keyframes "https://a.com/1.png,https://a.com/2.png,https://a.com/3.png" --poll  # Animação de quadros-chave

# ── Mecanismo de Vídeo Dois: Video 2.5 Flash (nova geração, 720P gratuito) ──
python scripts/agnes_client.py video25 "Ruas de cidade futurista após a chuva, reflexos de neon, movimento de câmera cinematográfico" --poll          # Texto para vídeo
python scripts/agnes_client.py video25 "Pessoa se vira naturalmente e caminha em direção à janela" --first-frame "https://.../f.png" --last-frame "https://.../l.png" --poll  # Quadro-chave início/fim
python scripts/agnes_client.py video25 "Correndo em um campo de flores com <Picture 1> como referência de personagem" --image-url "https://.../char.png" --poll  # Referência de imagem
python scripts/agnes_client.py video25 "Gerar cena noturna seguindo o ritmo de <Audio 1>" --audio-url "https://.../music.mp3" --poll  # Referência de áudio
python scripts/agnes_client.py video25 "..." --model agnes-video-2.5 --size 960P               # Upgrade pago (960P/2K)

# Apenas enviar tarefa de vídeo sem esperar
python scripts/agnes_client.py video "..." --no-poll
python scripts/agnes_client.py video25 "..." --no-poll

# Consultar status da tarefa de vídeo (recomendado usar --model para tarefas V2.5)
python scripts/agnes_client.py video-status TASK_ID
python scripts/agnes_client.py video-status TASK_ID --model agnes-video-2.5-flash

# Traduzir prompt em chinês
python scripts/agnes_client.py translate "Um gato"

# Compreensão de imagem / Vision (usar agnes-2.5-flash para analisar conteúdo de imagem)
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png"
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png" --prompt "Qual marca é este relógio?"

# Teste de fumaça (verificar conectividade da API)
python scripts/agnes_client.py smoke-test

Fluxo de Trabalho Completo

Fluxo de Texto para Imagem

Receber o prompt do usuário em chinês/inglês
Se contiver chinês e --no-translate não for especificado, chamar automaticamente agnes-2.5-flash para traduzir para inglês
Chamar POST /v1/images/generations (modelo padrão: agnes-image-2.5-flash)
Extrair URL da imagem de data[0].url na resposta
Retornar o resultado ao usuário (mostrar URL, ou tentar abrir com curl/navegador)

Recomendação de tamanho: Para texto para imagem, recomenda-se usar o formato "tamanho + proporção" como --size 2K --ratio 16:9 para obter tamanho previsível; Tamanhos exatos não suportados (como 1920x1080) serão normalizados pelo servidor, sendo necessário cortar manualmente.

Fluxo de Imagem para Imagem

Confirmar que o usuário forneceu URL da imagem de entrada ou caminho local
Se necessário, traduzir o prompt
Chamar o mesmo endpoint, passando o array de URLs da imagem de entrada em extra_body.image
Retornar o resultado gerado

Fluxo de Geração de Vídeo (Seleção de Mecanismo)

A Skill inclui dois mecanismos de vídeo, escolha conforme a necessidade:

Mecanismo	Subcomando	Modelo	Características	Preço
V2.0	`video`	`agnes-video-v2.0`	t2v/ti2vid/keyframes, taxa de quadros livre (num_frames 8n+1) e resolução	$0/segundo
Video 2.5	`video25`	`agnes-video-2.5-flash` (padrão) / `agnes-video-2.5` (pago)	Nova geração: texto/quadro-chave/referência, imagem/áudio de referência, câmera mais controlável	flash gratuito por tempo limitado

Fluxo de Trabalho Video 2.5 Flash (video25):

Inferir modo automaticamente com base no material (modo auto), ou especificar explicitamente:
- text: apenas texto → sem parâmetros de mídia
- keyframe: --first-frame / --last-frame (pelo menos um) restringem composição inicial/final
- reference: --image-url (≤5) / --audio-url (≤3); use placeholders <Picture N> / <Audio N> no prompt para referenciar material
Enviar POST /v1/videos, parâmetros: mode + seconds("4"~"12") + size(flash apenas 720P) + aspect_ratio + seed
Polling GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash (keyframe/reference devem incluir model_name)
Após status completed, extrair URL do vídeo da resposta

⚠️ Os sistemas de parâmetros de video25 e video são completamente diferentes: video25 não aceita num_frames/width/height/fps/negative_prompt (retorna 400).

Restrições de Parâmetros de Vídeo (Mecanismo Um V2.0)

num_frames deve satisfazer 8n + 1, máximo 441
Padrão: num_frames=121, frame_rate=24 (~5 segundos)
Para teste rápido use --num-frames 81 (~3,4 segundos)

Restrições de Parâmetros de Vídeo (Mecanismo Dois Video 2.5)

seconds como string "4"~"12", padrão "5"
size: flash fixo em 720P; modelo pago agnes-video-2.5 opcional 720P/960P/2K
aspect_ratio: 21:9 / 16:9(padrão) / 4:3 / 1:1 / 3:4 / 9:16
Restrições flash: imagens de referência ≤5, áudio ≤3, não suporta referência de vídeo (versão paga suporta videos)
Testado: saída 720P 16:9 aproximadamente 1280x704

Fluxo de Compreensão de Imagem (Vision)

O agnes-2.5-flash suporta entrada multimodal no formato OpenAI Vision API, podendo analisar conteúdo de imagem e retornar descrição textual. Esta é uma solução de ponte para "dar olhos a modelos sem capacidade visual". A capacidade de compreensão de imagem da versão 2.5 é mais forte que a 2.0, com reconhecimento de detalhes mais preciso.

Garanta que a imagem foi carregada em uma URL HTTP(S) acessível publicamente
Chame o comando vision, passando a URL da imagem + prompt de análise opcional
Retorna descrição textual, que pode ser passada diretamente como contexto para outros modelos (ex.: "Dê sugestões de melhoria para o design deste relógio na imagem" — primeiro vision obtém a descrição, depois passa para qualquer modelo de texto para análise)

Parâmetros do comando Vision:

--image-url (obrigatório, pode ser especificado múltiplas vezes): URLs das imagens a serem analisadas
--prompt (opcional): prompt de análise, padrão "Describe this image in detail."
--system (opcional): prompt do sistema
--max-tokens (opcional): número máximo de tokens de saída, padrão 1000
--no-translate (opcional): pular tradução automática (recomendado para prompts em inglês)

Melhores Práticas para Prompts

Estrutura de Prompt para Imagem

[Sujeito] + [Cena] + [Estilo] + [Iluminação] + [Composição] + [Qualidade]

Exemplo:

A luxury watch with a black leather strap on a marble surface, soft studio lighting, macro photography, 8K detail, high visual density

Prompt para Imagem para Imagem

Descreva claramente o que mudar + o que manter:

Transform the background to a dark luxury setting while preserving the watch design and angle.

Prompt para Vídeo

Incorpore movimento de câmera e elementos temporais:

A slow 360-degree rotation around the watch, revealing every detail, cinematic lighting, smooth movement

Preços

Modelo	Preço
`agnes-2.5-flash` (Texto/Vision/Raciocínio)	Gratuito ($0/1M tokens)
`agnes-image-2.5-flash` (Imagem, mais recente)	Gratuito ($0/imagem, todos os tamanhos 1K~4K)
`agnes-image-2.1-flash` (Imagem, geração anterior)	Gratuito ($0/imagem)
`agnes-video-v2.0` (Mecanismo de Vídeo Um)	Gratuito ($0/segundo)
`agnes-video-2.5-flash` (Mecanismo de Vídeo Dois)	Gratuito por tempo limitado ($0/segundo, 720P)
`agnes-video-2.5` (Vídeo, upgrade pago)	$0,025/segundo(720P) / $0,040/segundo(960P) / $0,055/segundo(2K)

Os preços seguem o site oficial https://www.agnes-ai.com/en/docs/pricing; a política gratuita pode ser ajustada conforme anúncios da plataforma.

Limitações Conhecidas

O modo 2.5 Thinking retorna o campo reasoning_content (processo de raciocínio), aumentando ligeiramente os tokens de saída
Geração de vídeo ocasionalmente apresenta erro de servidor division by zero
Vídeo com múltiplas imagens/quadros-chave do V2.0 ainda não foi totalmente validado de ponta a ponta
A API de imagem aceita apenas URLs HTTP(S) como entrada, não suporta base64 (entrada); a saída pode ser URL ou Base64
O agnes-video-2.5-flash suporta apenas 720P, sem referência de vídeo; para 960P/2K ou referência de vídeo, use o modelo pago --model agnes-video-2.5
Consultas de tarefa keyframe/reference no video25 devem incluir --model agnes-video-2.5-flash

Detecção Automática de Proporção (i2i)

Ao fazer i2i sem especificar --ratio, o script detecta automaticamente a proporção da imagem de referência principal (primeiro --image-url) e a mapeia para uma das 8 proporções oficiais suportadas pelo agnes-image-2.5-flash (1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9), evitando que a proporção da tela de saída seja inconsistente com o assunto de entrada, causando distorção de personagens.

# Detecção automática: exibirá [INFO] Main reference image: ... → auto ratio: ...
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --image-url REF_URL --size 2K

# Especificação manual (pula detecção automática)
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --ratio 16:9

Convenção de imagem de referência principal: O primeiro --image-url é considerado o assunto que determina a composição/proporção (geralmente modelo/produto); a segunda e posteriores são consideradas referências de estilo/detalhe. Para trocar a imagem de referência principal, basta inverter a ordem dos --image-url.

Referências

Documentação detalhada da API: references/api_reference.md
Site oficial: https://agnes-ai.com/
Plataforma da API: https://platform.agnes-ai.com/

Agnes multimodal

O que é Agnes multimodal?

Perguntar na sua IA favorita

Documentação