Endpoint /v1/images/generations: Primeiros Passos
Nesta página
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_ratiodefinido comoauto,resolutioncomo1k), parâmetroqualitypara o Imagine 2.0 e JPEG como formato predefinido. Fontes: Image Generation · Images API.
Gere a Sua Primeira Imagem com a API 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.
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-imageougrok-imagine-image-2.0, consulte a lição 2)prompt: a descrição textual da imagem desejadan: o número de imagens a gerar (de 1 a 10, predefinição: 1)aspect_ratio: a proporção da imagem (autopor predefinição: o modelo escolhe com base no prompt)resolution: a resolução (1kpor predefinição, ou2k)quality:low,mediumouauto(predefinição) no Imagine 2.0, consulte a lição 12response_format:url(predefinição) oub64_jsonpara 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 (seresponse_formatforurl)b64_json: os dados Base64 da imagem (seresponse_formatforb64_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:
modeleprompt - 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) e2k