HTML para Imagem
O que a ferramenta faz
Section titled “O que a ferramenta faz”HTML para Imagem é uma ferramenta nativa do agente. Ela envia um documento HTML/CSS a um serviço de renderização e devolve uma imagem estática. É indicada para cards, banners, cupons, recibos e posts cujo layout deve seguir regras explícitas.
Ela não funciona como a Gerar Imagem com LLM: o agente precisa compor a marcação, o CSS e o texto do resultado. Isso dá mais controle sobre estrutura e tipografia, mas não transforma uma descrição curta em uma ilustração generativa.
Permissão e ativação
Section titled “Permissão e ativação”Para abrir o editor do agente e alterar suas ferramentas, a pessoa precisa da
capacidade agents.write.
- Abra Agentes e selecione o agente.
- Entre em Ferramentas e escolha Adicionar Ferramenta.
- Em Ferramentas Nativas, selecione HTML para Imagem.
- Revise os quatro parâmetros e escolha IA decide ou Manual para cada um.
- Selecione Salvar.
A ferramenta já é criada como ativa. Não existe uma ativação separada na organização nem uma chave de provedor para configurar nessa tela.
Parâmetros
Section titled “Parâmetros”| Parâmetro | IA decide | Manual |
|---|---|---|
html | O agente deve enviar o documento HTML/CSS completo em cada chamada. | O mesmo HTML é usado em todas as chamadas. |
width | O agente pode escolher a largura; se não enviar, o runtime usa 1080. | Fixa a largura em pixels. |
height | O agente pode escolher a altura; se não enviar, o runtime usa 1080. | Fixa a altura em pixels. |
format | O agente pode escolher; se não enviar, o runtime usa webp. | Fixa webp, png ou jpeg. |
Um valor Manual deixa de ser exposto ao modelo e prevalece sobre qualquer
valor que ele tente enviar. Use isso para padronizar dimensões e formato. Deixe
html em IA decide quando o conteúdo ou o layout deve variar por pedido.
Como orientar o agente
Section titled “Como orientar o agente”O contrato da ferramenta pede HTML completo, com CSS inline ou dentro de
<style>. No prompt do agente, defina:
- objetivo e conteúdo obrigatório;
- largura, altura e formato quando não estiverem fixos;
- paleta, tipografia, espaçamento e hierarquia;
- quais dados podem variar e quais elementos devem permanecer constantes;
- texto alternativo que faça sentido quando a imagem for apresentada.
Exemplo de instrução:
Quando o cliente pedir um card de promoção, use HTML para Imagem. Crie um documento HTML completo, mantenha fundo azul-escuro, título branco e preço em destaque. Use 1080 × 1080 e WebP, salvo se o cliente pedir outro formato.
Depois de uma execução bem-sucedida, o agente recebe
{ "status": "success", "imageUrl": "..." } e deve apresentar a imagem em
Markdown. Ele é instruído a não repetir automaticamente a mesma renderização.
Em canais externos compatíveis, o pipeline extrai a imagem do Markdown para a
entrega; no Hub, ela aparece na própria resposta.
Confiabilidade e segurança do conteúdo
Section titled “Confiabilidade e segurança do conteúdo”- Prefira HTML autocontido, CSS inline ou
<style>e fontes do sistema. - Recursos remotos, fontes web, scripts, animações, datas e conteúdo dinâmico podem mudar o resultado ou falhar. Portanto, o mesmo HTML não garante a mesma imagem quando depende de estado externo.
- Não inclua segredos, tokens, dados pessoais desnecessários nem URLs internas no HTML. O documento é enviado a um serviço de renderização externo ao pipeline do SquadOS.
- Use dimensões positivas e moderadas. A interface não mostra limites mínimo e máximo; áreas maiores reduzem automaticamente a qualidade enviada ao serviço e podem aumentar tempo, tamanho e chance de falha.
- O repositório do SquadOS não contém o serviço HTML para Imagem. Por isso, a política de rede, a retenção do arquivo e o prazo de validade de uma URL retornada não estão comprovados pela implementação auditada. Não trate a URL como armazenamento permanente.
Falhas e consumo
Section titled “Falhas e consumo”Se faltar HTML, se o serviço não estiver configurado, se a resposta não contiver
imagem ou se a renderização falhar, a ferramenta devolve
{ "status": "error", "error": "..." }. O agente é orientado a explicar a
falha e a não tentar novamente sozinho. Em erro associado a timeout de 30
segundos, a mensagem pede simplificação do layout.
A execução não entra no ledger de modelo de imagem usado por Gerar Imagem com LLM. Ainda existe o consumo normal do modelo de texto que cria o HTML e conduz a conversa. O produto não apresenta, nessa configuração, um preço separado do serviço de renderização; não prometa que a operação é gratuita.