¿Cómo usar la API de imagen a imagen de Grok Image 2.0? Una imagen de referencia y una frase para editarla

¿Cómo usar la API de imagen a imagen de Grok Image 2.0? Envía una imagen de referencia accesible públicamente junto con una instrucción de edición, envíala con POST /v1/tasks y consulta hasta obtener data.output[0].url, que es la imagen ya editada. Precio fijo de $0.065 por imagen, 1K y 2K al mismo precio, sin máscaras ni capas.

Grok Image 2.0 ya está disponible en HiAPI. Abre la página del modelo de imagen a imagen, sube una imagen y edítala. Los usuarios nuevos reciben 200 créditos al registrarse, suficientes para 1 edición de imagen a imagen (130 créditos).

TL;DR

• Qué es: grok-imagine-image-2.0/image-to-image, creado por xAI, edita imágenes con una sola imagen de referencia más una instrucción en lenguaje natural: cambiar el fondo, añadir objetos pequeños, cambiar el color de un material, todo es posible.
• Cuánto cuesta: $0.065 por imagen; 1K / 2K y low / medium cuestan lo mismo; se cobra por imagen generada con éxito y se reembolsa automáticamente en caso de fallo. Con $10 salen unas 153 imágenes.
• Cómo llamarla lo más rápido: solo prompt e image son obligatorios; image es una cadena URL, no un array.

¿Qué parámetros tiene la imagen a imagen de Grok Image 2.0?

Campo	Obligatorio	Valores	Descripción
prompt	Sí	Cadena	Instrucción de edición
image	Sí	Cadena	URL pública de una imagen JPG / JPEG / PNG / WebP, no un array
resolution	No	1k, 2k	Por defecto 1k
quality	No	low, medium	Por defecto medium; medium da más detalle, low es más rápido
aspect_ratio	No	Los mismos 14 valores que texto a imagen	Se puede enviar, pero no tiene efecto; el formato de salida sigue a la imagen de referencia

Solo se puede editar una imagen de referencia por vez y cada tarea genera una imagen; para varias, envía varias tareas y ejecútalas en paralelo. Las solicitudes con nombres de campo o valores fuera de la tabla devuelven 400.

Dos rutas: probar en línea y usar la API

Prueba en línea (1 minuto)

1. Abre la página del modelo de imagen a imagen, inicia sesión y sube la imagen de referencia.
2. Escribe la instrucción de edición y elige la resolución.
3. Pulsa «Ejecutar» y, cuando la tarea termine, compara la imagen de referencia con el resultado.

Integración por API (5 minutos)

1. Crea una API Key en la consola.
2. Publica la imagen de referencia en una dirección accesible desde internet (tu propia CDN o almacenamiento de objetos).
3. Envía la tarea con POST /v1/tasks y consulta su estado o configura un callback.
4. En cuanto tenga éxito, descarga data.output[0].url.

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

Prueba directamente un prompt de edición: lleva al anciano luthier del taller de virutas de madera a un mercado soleado sin tocar a la persona. Generar con este prompt → (el enlace solo rellena el prompt; la imagen de referencia se sube en la página del modelo y la resolución se elige en 2K)

Imagen de referencia	Imagen generada

curl y Python: completa tu primera edición

Primero configura la API Key:

export HIAPI_API_KEY="sk-..."

Todas las solicitudes llevan Authorization: Bearer sk-<key>. La edición de imágenes es asíncrona y comparte la misma interfaz de tareas que el resto de modelos de HiAPI. La imagen de referencia la descarga el servidor, así que no sirve una ruta de archivo local: debe ser una URL accesible públicamente.

Paso 1, crear la tarea:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

Devuelve inmediatamente un taskId:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q" }
}

Paso 2, consultar hasta el estado final:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Consulta data.status: success indica éxito y fail indica fallo; con cualquier otro estado, sigue esperando. Ejemplo de respuesta correcta:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Ojo con storage: "temp" y expireAt: la dirección de la imagen generada es temporal; descárgala en cuanto termine la tarea o guárdala en tu propio almacenamiento de objetos. El formato de salida sigue a la imagen de referencia; en el ejemplo se omite aspect_ratio porque no tiene efecto.

Versión en Python:

Primero instala requests (python3 -m pip install requests) y configura la HIAPI_API_KEY anterior. El script consulta durante un máximo de 10 minutos; si se agota el tiempo, conserva el taskId para seguir consultando.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

¿En qué fijarse antes de salir a producción?

• Publica primero la imagen de referencia en internet. Si la imagen que sube el usuario está en un bucket privado o en localhost, la plataforma no puede descargarla y la tarea fallará de forma asíncrona; antes de enviarla, confirma que el enlace es accesible públicamente y usa una dirección de larga duración (no enlaces firmados que caducan).

• Escribe la instrucción como «qué mantener y qué cambiar solo». Primero lo que no debe cambiar, después lo que hay que modificar; cuanto más estrecho el alcance del cambio, más estable. Más formas de escribirla en plantillas de prompts de imagen a imagen.

• Para lotes, usa callbacks y no un bucle de consulta ajustado.

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" notifica cuando la tarea alcanza el estado final de éxito o fallo; el receptor deduplica por taskId.

• Guarda la imagen generada de inmediato. data.output[0].url es una dirección temporal que caduca según expireAt.

• Envía cada tarea una sola vez. Al recibir la respuesta, guarda la correspondencia entre el taskId y tu tarea de negocio; reenviar puede crear varias tareas y cobrarse por separado. Si la solicitud de creación agota el tiempo sin recibir el ID, revisa primero el registro de tareas y luego decide si reenviar.

• Especifica resolution explícitamente. Por defecto es 1k; 1K y 2K cuestan lo mismo ($0.065), así que para el resultado final pasa directamente "2k".

• Manejo de errores. Revisa primero el estado HTTP y los campos code y message de la respuesta, y luego lee data. Los errores de parámetros o de autenticación deben corregirse antes de reenviar; si la tarea devuelve fail, registra el error y deja de consultar.

Lecturas relacionadas

• Página del modelo de texto a imagen de Grok Image 2.0: de la misma serie, genera imágenes nuevas solo con texto.
• ¿Cuánto cuesta la API de Grok Image 2.0?
• Integración de la API de texto a imagen de Grok Image 2.0
• Plantillas de prompts de imagen a imagen de Grok Image 2.0
• Autenticación e inicio rápido

Preguntas frecuentes

¿image recibe una URL o un array? Una cadena URL. Pasar un array da error de tipo. Si necesitas combinar varias imágenes, usa un modelo que admita varias imágenes de referencia.

¿Qué hago si aparece «additional properties not allowed»? input solo acepta prompt, image, aspect_ratio, resolution y quality. Otros campos habituales en modelos de edición como image_urls, strength, mask, seed y negative_prompt no están disponibles aquí; elimínalos.

El navegador abre la imagen de referencia, ¿por qué puede fallar la tarea? La plataforma descarga la imagen en el servidor, así que la referencia no debe requerir inicio de sesión y debe ser accesible desde internet; los enlaces firmados deben seguir vigentes hasta que termine la descarga. Revisa permisos de acceso, formato y vigencia del enlace antes de enviar.

¿Se pueden editar varias imágenes a la vez? No: entra una imagen y sale una imagen. Para lotes, envía varias tareas y ejecútalas en paralelo.

¿Por qué la imagen a imagen cuesta más que la de texto a imagen? La imagen a imagen cuesta $0.065 y la de texto a imagen $0.052, un 25% más, que corresponde a la capacidad de «editar con una imagen de referencia».

¿Cuánto dura la dirección de salida? Es almacenamiento temporal; el expireAt de la respuesta es una marca de tiempo Unix. Descarga o guarda la imagen en cuanto la tarea termine.

¿Hay que esperar el resultado de forma síncrona? No. La interfaz de creación responde en cuanto la tarea entra en cola; en scripts cortos, consulta con GET /v1/tasks/<taskId>; en producción, configura callback.

Edita ahora tu primera imagen

Configura primero HIAPI_API_KEY y luego sustituye la dirección image de los ejemplos curl y Python por la URL pública de tu propia imagen. Si quieres ver el resultado antes, abre la página del modelo de imagen a imagen, sube una imagen y pega el prompt de arriba.