Punto de conexión /v1/images/generations: primeros pasos
En esta página
Lección completada el 3 de noviembre de 2026 sobre la base de la página Image Generation y la referencia de la API de Imágenes de xAI: valores predeterminados (
aspect_ratioestablecido enauto,resolutionen1k), parámetroqualitypara Imagine 2.0 y JPEG como formato predeterminado. Fuentes: Image Generation · Images API.
Genera tu primera imagen con la API de Grok
La API de xAI ofrece un punto de conexión dedicado a la generación de imágenes: POST /v1/images/generations. Este endpoint te permite crear imágenes a partir de una descripción de texto utilizando los modelos Grok Imagine. Tanto si quieres producir ilustraciones, material de marketing o prototipos creativos, todo comienza con este punto de conexión.
En esta lección aprenderás a estructurar una solicitud de generación de imágenes y a comprender los parámetros fundamentales.
Estructura de una solicitud de generación
Bastan dos parámetros para generar una imagen: el modelo y el prompt (instrucción). El resto tienen valores predeterminados, lo que te permite obtener un primer resultado en tres líneas; y eso es exactamente lo que debes hacer antes de seguir leyendo, para tener una imagen delante y poder relacionar cada parámetro con ella.
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="Un faro bretón bajo un cielo estrellado, estilo acuarela"
)
image_url = response.data[0].url
print(image_url)
La API de xAI es compatible con el SDK de OpenAI para la generación de imágenes: solo tienes que apuntar base_url a https://api.x.ai/v1, proporcionar tu clave de xAI y el resto de tu código permanece sin cambios. Ten presente el alcance de esta compatibilidad: se aplica a la generación, pero no a la edición, que espera un formato distinto. La lección 5 aborda este punto.
Parámetros de la solicitud
Estos son los parámetros que puedes incluir en tu solicitud:
model: el modelo de generación que se va a utilizar (grok-imagine-imageogrok-imagine-image-2.0, consulta la lección 2)prompt: la descripción textual de la imagen deseadan: el número de imágenes a generar (de 1 a 10; predeterminado: 1)aspect_ratio: la relación de aspecto de la imagen (autopor defecto: el modelo elige en función del prompt)resolution: la resolución (1kpor defecto, o2k)quality:low,mediumoauto(predeterminado) en Imagine 2.0, consulta la lección 12response_format:url(predeterminado) ob64_jsonpara recibir la imagen en Base64
Ejemplo con todos los parámetros
response = client.images.generate(
model="grok-imagine-image",
prompt="Un bosque encantado con luciérnagas, estilo arte digital",
n=2,
response_format="url",
extra_body={"aspect_ratio": "16:9", "resolution": "2k"},
)
for image in response.data:
print(image.url)
Formato de la respuesta
La respuesta es siempre un array, incluso para una sola imagen; itera sobre él en lugar de leer directamente data[0], de lo contrario tu código fallará el día que establezcas n=4. Cada objeto contiene:
url: la URL temporal de la imagen (siresponse_formatesurl)b64_json: los datos Base64 de la imagen (siresponse_formatesb64_json)
El tipo MIME devuelto puede ser image/png, image/jpeg o image/webp; por defecto es image/jpeg, a menos que una configuración de calidad produzca PNG.
Práctica guiada
Prueba a generar tu primera imagen adaptando el prompt a tu contexto profesional. Por ejemplo, para un visual de presentación:
response = client.images.generate(
model="grok-imagine-image",
prompt="Gráfico minimalista que muestra el crecimiento de una startup, "
"colores azul y blanco, fondo oscuro, estilo de diseño plano",
extra_body={"resolution": "2k", "aspect_ratio": "16:9"},
)
Puntos clave
- El punto de conexión de generación es
POST /v1/images/generations - Bastan dos parámetros para empezar:
modelyprompt - La API es compatible con el SDK de Python de OpenAI cambiando el
base_url - Puedes generar hasta 10 imágenes por solicitud
- Las resoluciones disponibles son
1k(predeterminada) y2k