Ir al contenido principal
Español— Elegir un idioma
Menú

Endpoint /v1/images/edits: Edita tus imágenes

Lección 5 de 14 Actualizado el 2 de noviembre de 2026 Principiante
En esta página
  1. Edición de imágenes con la API de Grok
  2. Estructura de la solicitud de edición
  3. ¿Por qué usar requests en lugar del SDK de OpenAI?
  4. Parámetros del endpoint de edición
  5. Tipos de ediciones posibles
  6. Práctica guiada
  7. Puntos clave

Actualizado el 2 de noviembre de 2026 — Imagine. grok-imagine-image-quality se eliminó el 2 de noviembre de 2026 (sus solicitudes las atiende Imagine 2.0 con calidad low): los ejemplos ahora usan grok-imagine-image (Imagine 1.0) y grok-imagine-image-2.0 (Imagine 2.0, con calidad low, medium o auto). Con el SDK de OpenAI, aspect_ratio, resolution y quality se pasan mediante extra_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.

5
Imágenes de origen máximas
2
Formatos de entrada
JSON
Content-Type obligatorio
∞
Rondas de edición

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) o grok-imagine-image-2.0 (Imagine 2.0, que también acepta quality)
  • prompt (obligatorio): descripción de la modificación a aplicar
  • image: objeto que contiene la URL de una única imagen de origen
  • images: array de objetos para varias imágenes de origen (excluyente mutuamente con image)
  • mask: objeto que contiene la URL de la máscara del área a editar
  • n: número de variantes a generar (de 1 a 10)
  • response_format: url o b64_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 requests en 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