Endpoint /v1/images/edits: Edita tus imágenes
En esta página
Actualizado el 2 de noviembre de 2026 — Imagine.
grok-imagine-image-qualityse eliminó el 2 de noviembre de 2026 (sus solicitudes las atiende Imagine 2.0 con calidadlow): los ejemplos ahora usangrok-imagine-image(Imagine 1.0) ygrok-imagine-image-2.0(Imagine 2.0, con calidadlow,mediumoauto). Con el SDK de OpenAI,aspect_ratio,resolutionyqualityse pasan medianteextra_body, y la edición requiere el SDK de xAI o una petición HTTP directa.
Edición de imágenes con la API de Grok
Más allá de la generación, la API de xAI ofrece un endpoint dedicado para editar imágenes existentes: POST /v1/images/edits. Este endpoint te permite modificar, transformar o mejorar imágenes describiendo los cambios deseados en un prompt de texto sencillo.
Estructura de la solicitud de edición
La edición funciona de forma similar a la generación, con una diferencia que lo cambia todo a la hora de escribir los prompts: el prompt describe la modificación, no la imagen final. «Una mujer con gafas de sol» regenera una imagen completa; «añade gafas de sol» mantiene la foto e interviene solo en ese punto. Esta es la confusión más habitual en el primer intento y explica la mayoría de los resultados decepcionantes.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-image",
"prompt": "Añade un sombrero rojo al personaje",
"image": {
"url": "https://exemple.com/photo-personnage.jpg"
}
}
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
result = response.json()
edited_url = result["data"][0]["url"]
¿Por qué usar requests en lugar del SDK de OpenAI?
Aquí está la trampa técnica de esta lección, y querrás saberlo antes de perder una hora con ello: la compatibilidad con el SDK de OpenAI, que funciona a la perfección para la generación, se detiene en la edición. El endpoint de edición de xAI utiliza un formato JSON, mientras que el método images.edit() del SDK envía multipart/form-data. Esta incompatibilidad de tipo de contenido significa que debes usar la API REST directamente con la biblioteca requests para las ediciones.
# NO FUNCIONA con la API de xAI
# client.images.edit(...) # Envía multipart, no JSON
# FUNCIONA: llamada REST directa
requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
Parámetros del endpoint de edición
model(obligatorio):grok-imagine-image(Imagine 1.0) ogrok-imagine-image-2.0(Imagine 2.0, que también aceptaquality)prompt(obligatorio): descripción de la modificación a aplicarimage: objeto que contiene la URL de una única imagen de origenimages: array de objetos para varias imágenes de origen (excluyente mutuamente conimage)mask: objeto que contiene la URL de la máscara del área a editarn: número de variantes a generar (de 1 a 10)response_format:urlob64_json
Tipos de ediciones posibles
Las cinco familias siguientes no comparten la misma tasa de éxito, y ayuda saberlo antes de prometer un resultado. Añadir elementos y cambiar la ambientación funcionan muy bien porque se apoyan en contenido existente. La eliminación es más delicada: el modelo debe reconstruir lo que había detrás del elemento eliminado, y aquí es donde la máscara resulta esencial, al delimitar con precisión el área que debe recalcularse.
- Añadir elementos: «Añade gafas de sol al personaje»
- Eliminación: «Elimina el fondo y sustitúyelo por un fondo blanco»
- Transformación de estilo: «Convierte esta foto en una ilustración a la acuarela»
- Modificación de la ambientación: «Cambia la escena de día a noche»
- Corrección: «Mejora la iluminación y aumenta el contraste»
# Ejemplo: cambiar el estilo de una imagen
payload = {
"model": "grok-imagine-image",
"prompt": "Transforma esta foto en una ilustración al estilo de cómic franco-belga",
"image": {
"url": "https://exemple.com/photo-ville.jpg"
}
}
Práctica guiada
Prueba a editar una imagen en varios pasos. Comienza con una modificación sencilla y luego refínala:
# Paso 1: modificar el fondo
payload_step1 = {
"model": "grok-imagine-image",
"prompt": "Sustituye el fondo por una puesta de sol sobre el océano",
"image": {"url": "https://exemple.com/portrait.jpg"}
}
Puntos clave
- El endpoint de edición es
POST /v1/images/edits - Usa
requestsen Python, no el SDK de OpenAI (incompatibilidad de formato) - Puedes proporcionar hasta 5 imágenes de origen por solicitud
- El prompt describe la modificación deseada en lenguaje natural
- Ambos modelos (Imagine 1.0 e Imagine 2.0) están disponibles para edición; con el SDK de OpenAI,
images.edit()no es compatible con xAI: usa el SDK de xAI o una petición HTTP