Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Ferramenta image_generation: Criar Imagens

Aula 10 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Gerar Imagens Através do Seu Agente
  2. Criar um Agente com Geração de Imagens
  3. Gerar uma Imagem
  4. Transferir Imagens Geradas
  5. Três Casos de Uso Comuns
  6. Combinar com Outras Ferramentas
  7. Escrever Bons Prompts de Imagem
  8. Gerir Ficheiros Gerados
  9. Pontos-chave

Gerar Imagens Através do Seu Agente

A ferramenta image_generation permite que o seu agente crie imagens a partir de descrições em texto. Complementa as ferramentas que já conheceu: enquanto a code_interpreter produz números e gráficos, esta gera elementos visuais. É uma ferramenta poderosa para casos de uso criativos, geração de maquetes ou ilustração de conceitos. Tal como outras ferramentas integradas, ativa-a ao criar o agente, e o modelo decide se a invoca com base no pedido.

Criar um Agente com Geração de Imagens

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Creative Agent",
    instructions="""You are a creative assistant specialized in image generation.
- Rephrase requests into detailed prompts for better results
- Describe the image you are about to generate before creating it
- Propose variations if the result is unsatisfactory""",
    tools=[{"type": "image_generation"}],
    completion_args={"temperature": 0.3, "top_p": 0.95}
)

As instruções têm aqui um peso significativo. Ao pedir ao agente que reformule o pedido num prompt detalhado, transforma um vago “faz-me uma imagem de um gato” numa descrição executável. Ao fazê-lo anunciar a imagem antes de a gerar, dá a si próprio a hipótese de corrigir a rota antes da geração ocorrer. Uma temperatura de 0,3 mantém esta reformulação disciplinada: pretende precisão descritiva, não invenção livre.

Gerar uma Imagem

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Generate an image of an orange cat in a modern office."
)

Por detrás desta única chamada, o agente encadeia quatro passos: analisa o seu pedido, formula um prompt otimizado para o modelo de geração, cria a imagem e devolve o ficheiro. Estes passos aparecem nos outputs da conversa, permitindo-lhe ver qual o prompt que produziu qual imagem. Isto é invaluable quando um resultado lhe agrada e deseja reproduzi-lo.

Transferir Imagens Geradas

As imagens não são devolvidas como texto na resposta: chegam como objetos ToolFileChunk no conteúdo, e recupera o ficheiro real através da API de Ficheiros.

from mistralai.client.models import ToolFileChunk

for i, chunk in enumerate(response.outputs[-1].content):
    if isinstance(chunk, ToolFileChunk):
        # Transferir o ficheiro de imagem
        file_bytes = client.files.download(file_id=chunk.file_id).read()

        # Guardar localmente
        with open(f"image_{i}.png", "wb") as f:
            f.write(file_bytes)
        print(f"Image saved: image_{i}.png")

Três Casos de Uso Comuns

O primeiro é a ilustração de documentação, onde um diagrama explica melhor do que um parágrafo.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Create a visual diagram showing a microservices architecture with an API Gateway, 3 services, and a database."
)

O segundo são maquetes visuais, para materializar uma direção antes de envolver um designer.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Generate a homepage mockup for an online learning website, modern and minimalist style with blue tones."
)

O terceiro é a criação de conteúdo de marketing, onde o agente produz um visual personalizado a partir de um brief escrito.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Create a promotional banner for an AI course, with the text 'Master AI in 2026' on a tech background."
)

Em todos os três casos, a qualidade do brief determina a qualidade do resultado: um agente criativo não inventa a sua intenção, executa-a.

Combinar com Outras Ferramentas

A geração de imagens atinge o seu pleno potencial quando emparelhada com outras ferramentas. Pesquisar dados, analisá-los e depois ilustrá-los torna-se num fluxo único e contínuo da perspetiva do utilizador.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Multimodal Agent",
    description="Search, code, and images.",
    instructions="Use search to find data, code to analyze it, and image generation to illustrate it.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"},
        {"type": "image_generation"}
    ]
)

Escrever Bons Prompts de Imagem

Cinco alavancas melhoram significativamente os resultados. Primeiro, seja descritivo: “Um gato laranja às riscas sentado numa secretária de madeira, iluminação natural, estilo fotográfico” produz uma imagem completamente diferente de “um gato”. De seguida, especifique o estilo esperado — fotográfico, ilustração, aguarela, minimalista. Indique a composição, ou seja, vista frontal, ângulo elevado, plano aproximado ou plano geral. Mencione a iluminação, seja natural, de estúdio, contraluz ou hora dourada. Por fim, especifique as cores: paleta quente, tons frios, monocromático. Estes cinco eixos são exatamente o que escreve nas instruções do agente para que este possa enriquecer pedidos excessivamente curtos dos seus utilizadores.

Gerir Ficheiros Gerados

As imagens geradas são armazenadas temporariamente na nuvem da Mistral através da API de Ficheiros. Adote o hábito de inventariar e limpar: caso contrário, o seu espaço enche-se de rascunhos esquecidos e os ficheiros de que necessitava desaparecem por não terem sido transferidos a tempo.

# Listar ficheiros
files = client.files.list()
for f in files.data:
    print(f"{f.id} — {f.filename} — {f.bytes} bytes")

# Eliminar um ficheiro
client.files.delete(file_id="file-xxxxxxxx")

Pontos-chave

  • image_generation cria imagens a partir de descrições em texto
  • As imagens são devolvidas como objetos ToolFileChunk e podem ser transferidas via client.files.download()
  • Prompts detalhados (estilo, composição, iluminação) melhoram significativamente os resultados
  • A ferramenta pode ser combinada com web_search e code_interpreter
  • Os ficheiros gerados são temporários — transfira-os ou serão eliminados