¿Cómo usar la API de texto a imagen de Grok Image 2.0? Genera tu primera imagen en 5 minutos

¿Cómo usar la API de texto a imagen de Grok Image 2.0? Tres pasos: POST /v1/tasks crea la tarea, tras obtener el taskId consulta en bucle (o configura un callback) y descarga la imagen generada desde data.output[0].url. $0.052 por imagen; 1K y 2K al mismo precio.

Grok Image 2.0 ya está disponible en HiAPI. Abre la página del modelo y genera directamente; los nuevos usuarios registrados reciben 200 créditos, suficientes para generar 1 imagen y ver el resultado.

TL;DR

• Qué es: grok-imagine-image-2.0/text-to-image, un modelo de texto a imagen de xAI que usa la interfaz unificada de tareas asíncronas de HiAPI.
• Cuánto cuesta: $0.052 por imagen; 1K / 2K, low / medium y cualquier relación de aspecto tienen este precio; se cobra por imagen generada con éxito y se reembolsa automáticamente en caso de fallo. Con $10 se generan unas 192 imágenes.
• Cómo llamarlo lo más rápido posible: basta con un prompt para generar una imagen; opcionalmente se pueden usar los tres parámetros aspect_ratio, resolution y quality.

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

input solo tiene cuatro campos:

Campo	Obligatorio	Valores	Descripción
prompt	Sí	Cadena	Descripción de la imagen
aspect_ratio	No	1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20、auto	Por defecto 1:1
resolution	No	1k、2k	Por defecto 1k
quality	No	low、medium	Por defecto medium; medium ofrece mejores detalles, low es más rápido

Cada tarea genera 1 imagen; para lotes, envía varias tareas en paralelo. Los campos o valores fuera de la tabla anterior devuelven 400, y el mensaje de error indica el campo concreto.

Dos vías: prueba en línea y API

Prueba en línea (1 minuto)

1. Abre la página del modelo de texto a imagen e inicia sesión.
2. Introduce el prompt y elige la relación de aspecto y la resolución.
3. Haz clic en «Ejecutar»; cuando la tarea termine correctamente, revisa y descarga la imagen generada.

Integración con la API (5 minutos)

1. Crea una API Key en la consola.
2. Envía la tarea con POST /v1/tasks.
3. Consulta en bucle GET /v1/tasks/<taskId> o configura un callback.
4. Cuando termine correctamente, descarga inmediatamente data.output[0].url.

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

Primero consigue un prompt que funcione: el siguiente es una imagen de producto 3:2. Genera con este prompt → (elige relación 3:2 y resolución 2K)

curl y Python: genera tu primera imagen

Primero configura la API Key:

export HIAPI_API_KEY="sk-..."

Todas las solicitudes incluyen Authorization: Bearer sk-<key>. La generación de imágenes es asíncrona y comparte la misma interfaz de tareas que otros modelos de HiAPI.

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/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

Devuelve inmediatamente el taskId:

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

Paso 2: consulta en bucle hasta el estado final:

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

Consulta data.status: success indica éxito, fail indica fallo; con otros estados, sigue esperando. Ejemplo de respuesta exitosa:

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

Ten en cuenta storage: "temp" y expireAt: la URL de la imagen generada es temporal; descárgala en cuanto termine la tarea o guárdala en tu propio almacenamiento de objetos.

Versión en Python:

Primero instala requests (python3 -m pip install requests) y configura la HIAPI_API_KEY anterior. El script consulta en bucle 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 generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "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 = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

¿Qué tener en cuenta antes de lanzar a producción?

• Para lotes, usa callbacks en lugar de consultas en bucle ajustadas. Incluye callback al crear la tarea y HiAPI enviará una notificación a tu dirección cuando termine:

  {
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": { "prompt": "..." },
    "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 debe deduplicar por taskId. Para páginas interactivas, usa consultas en bucle; para procesamiento por lotes, usa callbacks.

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

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

• Especifica resolution explícitamente. Por defecto es 1k; 1K y 2K cuestan lo mismo, así que para la versión final envía directamente "resolution": "2k".

• Para ajustar el prompt, usa quality: low. Mismo precio y respuesta más rápida; cambia a medium para la versión definitiva.

• Gestión de errores. Comprueba primero el estado HTTP y los campos code y message de la respuesta, y luego lee data. Si hay errores de parámetros o autenticación, corrígelos antes de reenviar; si la tarea devuelve fail, registra el error y detén la consulta en bucle.

Lecturas relacionadas

• ¿Cuánto cuesta la API de Grok Image 2.0? Texto a imagen a $0.052 por imagen, sin recargo por 2K
• Prompts de texto a imagen de Grok Image 2.0: 5 escenarios para copiar y generar directamente
• Integración de la API de imagen a imagen de Grok Image 2.0: editar con una sola imagen de referencia
• Grok Image 2.0 vs GPT Image 2: comparación con el mismo prompt
• Autenticación e inicio rápido

Preguntas frecuentes

¿Cómo se escribe el ID del modelo? Escribe el completo grok-imagine-image-2.0/text-to-image, conservando el número de versión 2.0 y /text-to-image.

¿Qué hacer si aparece "additional properties not allowed"? input solo acepta los cuatro campos prompt, aspect_ratio, resolution y quality; size, n, seed, negative_prompt y output_format, habituales en otros modelos, no están disponibles aquí; simplemente elimínalos.

¿Se pueden generar varias imágenes a la vez? No, cada tarea genera 1 imagen. Si necesitas varias, envía varias tareas y ejecútalas en paralelo.

¿Cuánto tiempo es válida la URL 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 correctamente.

¿Hay que esperar el resultado de forma síncrona? No. La interfaz de creación devuelve inmediatamente después de encolar la tarea; para scripts cortos, consulta en bucle GET /v1/tasks/<taskId>; en producción, configura callback.

¿Se cobra por las tareas fallidas? No; se cobra por imagen generada con éxito y se reembolsa automáticamente en caso de fallo. Cuando data.status es fail, detén la consulta en bucle.

Genera ahora tu primera imagen

Primero configura HIAPI_API_KEY, crea una tarea con el curl anterior y consulta con el data.taskId devuelto; cuando la tarea termine correctamente, descarga desde data.output[0].url. Si quieres ver el resultado antes, abre la página del modelo de texto a imagen; los 200 créditos de registro bastan para generar 1 imagen.