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

Endpoint /v1/images/generations: Primeiros Passos

Aula 1 de 14 Atualizada a 3 de novembro de 2026 Iniciante
Nesta página
  1. Gere a Sua Primeira Imagem com a API Grok
  2. Estrutura de um Pedido de Geração
  3. Parâmetros do Pedido
  4. Formato da Resposta
  5. Prática
  6. Pontos-chave

Lição concluída a 3 de novembro de 2026 com base na página Image Generation e na referência da API de Imagens da xAI: valores predefinidos (aspect_ratio definido como auto, resolution como 1k), parâmetro quality para o Imagine 2.0 e JPEG como formato predefinido. Fontes: Image Generation · Images API.

Gere a Sua Primeira Imagem com a API Grok

Imagem gerada pelo Grok A API da xAI disponibiliza um endpoint dedicado à geração de imagens: POST /v1/images/generations. Este endpoint permite criar imagens a partir de uma descrição textual utilizando os modelos Grok Imagine. Quer pretenda produzir ilustrações, elementos visuais de marketing ou protótipos criativos, tudo começa neste endpoint.

Nesta lição, irá aprender a estruturar um pedido de geração de imagens e a compreender os parâmetros fundamentais.

1
Endpoint de Geração
2
Modelos Disponíveis
10
Máximo de Imagens por Pedido
2k
Resolução Máxima

Estrutura de um Pedido de Geração

Dois parâmetros são suficientes para gerar uma imagem: o modelo e o prompt. Todos os outros possuem valores predefinidos, o que lhe permite obter um primeiro resultado em apenas três linhas de código — e é exatamente isso que deve fazer antes de ler o restante, para ter uma imagem diante de si e associar cada parâmetro ao seu efeito.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.images.generate(
    model="grok-imagine-image",
    prompt="A Breton lighthouse under a starry sky, watercolor style"
)

image_url = response.data[0].url
print(image_url)

A API da xAI é compatível com o SDK da OpenAI para geração de imagens: basta apontar o base_url para https://api.x.ai/v1, fornecer a sua chave xAI e o restante do seu código permanece inalterado. Tenha em mente o âmbito desta compatibilidade — aplica-se à geração, mas não à edição, que exige um formato diferente. A Lição 5 aborda este tema.

Parâmetros do Pedido

Eis os parâmetros que pode incluir no seu pedido:

  • model: o modelo de geração a utilizar (grok-imagine-image ou grok-imagine-image-2.0, consulte a lição 2)
  • prompt: a descrição textual da imagem desejada
  • n: o número de imagens a gerar (de 1 a 10, predefinição: 1)
  • aspect_ratio: a proporção da imagem (auto por predefinição: o modelo escolhe com base no prompt)
  • resolution: a resolução (1k por predefinição, ou 2k)
  • quality: low, medium ou auto (predefinição) no Imagine 2.0, consulte a lição 12
  • response_format: url (predefinição) ou b64_json para receber a imagem em Base64

Exemplo com Todos os Parâmetros

response = client.images.generate(
    model="grok-imagine-image",
    prompt="An enchanted forest with fireflies, digital art style",
    n=2,
    response_format="url",
    extra_body={"aspect_ratio": "16:9", "resolution": "2k"},
)

for image in response.data:
    print(image.url)

Formato da Resposta

A resposta é sempre um array, mesmo para uma única imagem — percorra-o em vez de ler apenas data[0], caso contrário o seu código falhará no dia em que definir n=4. Cada objeto contém:

  • url: o URL temporário da imagem (se response_format for url)
  • b64_json: os dados Base64 da imagem (se response_format for b64_json)

O tipo MIME devolvido pode ser image/png, image/jpeg ou image/webp; a predefinição é image/jpeg, a menos que uma definição de qualidade produza PNG.

Prática

Experimente gerar a sua primeira imagem adaptando o prompt ao seu contexto profissional. Por exemplo, para um visual de apresentação:

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Minimalist chart showing startup growth, "
           "blue and white colors, dark background, flat design style",
    extra_body={"resolution": "2k", "aspect_ratio": "16:9"},
)

Pontos-chave

  • O endpoint de geração é POST /v1/images/generations
  • Dois parâmetros são suficientes para começar: model e prompt
  • A API é compatível com o SDK Python da OpenAI alterando o base_url
  • Pode gerar até 10 imagens por pedido
  • As resoluções disponíveis são 1k (predefinição) e 2k