Grok Imagine Image Quality · API

Inicio rápido

Tres pasos: envía un trabajo, consúltalo y toma el enlace de la imagen. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

Paso 1 · Envía el trabajo (devuelve al momento un id de trabajo, HTTP 202)

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image-quality", "prompt": "Un zorro rojo en un bosque nevado al amanecer, fotorrealista", "size": "16:9", "resolution": "2K"}'

Respuesta (HTTP 202)

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "grok-imagine-image-quality"
}

Paso 2 · Consulta cada 2–3 segundos hasta que status sea succeeded o failed

curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

Respuesta cuando sale bien

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "grok-imagine-image-quality",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "grok-imagine-image-quality"}
}

Paso 3 · data[0].url es la imagen (PNG). Se guarda 15 días; descárgala en tu propio almacenamiento para conservarla más tiempo.

Ejemplo completo (Python: enviar, esperar y guardar en disco)

import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. enviar el trabajo
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "grok-imagine-image-quality",
    "prompt": "Un zorro rojo en un bosque nevado al amanecer, fotorrealista",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 3 segundos hasta que termine
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. descargar la imagen
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("grok-imagine-image-quality.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

Parámetros de la petición

El cuerpo JSON de POST /v1/images/generations:

Los demás parámetros de OpenAI (quality, background, output_format, response_format y similares) no cambian el precio y no se garantiza que tengan efecto; los resultados siempre son PNG y se devuelven como url.

Precio

Se cobra por imagen, solo según el nivel: la proporción y que sea texto a imagen o imagen a imagen no cambian nada. El precio del nivel se retiene al enviar y se reembolsa íntegro si el trabajo falla. 1 crédito = $0.005.

Proporción, resolución y tamaño de salida

Pon la proporción en size y el nivel en resolution. La imagen se entrega exactamente con el tamaño de la tabla: el nivel fija el lado más largo y el otro lado se ajusta a la proporción. Las proporciones que no están en la tabla funcionan igual.

• El modelo compone la imagen en el formato horizontal, vertical o cuadrado más cercano, y luego la pasarela la recorta al centro y la redimensiona al tamaño de la tabla; cuanto más se aleja una proporción de 3:2, 2:3 o 1:1, más se recortan los bordes. La pasarela añade a tu prompt una frase sobre la proporción (en inglés) para que el sujeto quede completo y centrado; mantén lejos de los bordes todo lo que no deba perderse.
• size también puede ser un tamaño en píxeles (por ejemplo, 1536x1024): la imagen se entrega exactamente con ese tamaño (reducida si el lado más largo supera 4096). El nivel lo marca entonces resolution o, si no lo envías, el lado más largo: hasta 1536 es 1K, hasta 2048 es 2K, y por encima es 4K. resolution puede subir el nivel, pero nunca bajarlo, y no cambia el tamaño entregado, así que no combines un tamaño pequeño con un nivel alto.
• Este modelo solo tiene 1K y 2K: si pides 4K (resolution: "4K", o un size cuyo lado más largo supera 2048), se rechaza al momento con 400 unsupported_resolution y no se cobra nada. Para 2K, envía resolution: "2K".

Imagen a imagen e imágenes de referencia

• Envía image (una imagen) o images (varias, hasta 8; las que pasen de 8 no se usan) y el trabajo será de imagen a imagen; indica en el prompt qué cambiar. POST /v1/images/edits acepta los mismos parámetros.
• Los dos endpoints solo aceptan un cuerpo JSON, no la subida de archivos multipart, así que images.edit() del SDK de OpenAI no se puede usar tal cual: pasa enlaces o base64 como en el ejemplo de abajo.
• Cada referencia puede ser una URL pública de imagen (http o https), un data: URI o base64 puro, de hasta 16MB cada una, en un formato habitual como JPEG, PNG o WebP.
• La URL tiene que descargar directamente la imagen: no puede ser una página web ni estar detrás de un inicio de sesión o de una protección contra hotlinking. Una referencia que no podemos leer se rechaza al enviar con un 400 que indica cuál es y por qué; no se crea ningún trabajo y no se cobra nada.
• La proporción de salida la marca size, no la referencia. Para mantener la proporción original, pon esa proporción en size.
• Alojamos las referencias por ti y las guardamos 7 días.

Imagen a imagen con dos referencias

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image-quality", "prompt": "Mantén a las personas y cambia el fondo por una playa de noche con guirnaldas de luces cálidas", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Estado y campos del trabajo

GET /v1/images/jobs/{id} devuelve estos estados; cada campo se describe en Trabajos asíncronos. Consulta cada 2–3 segundos o usa un webhook.

Cada cuenta ejecuta hasta 50 trabajos a la vez; los demás esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa íntegro. Los registros de trabajos se guardan 3 días y los enlaces de las imágenes, 15 días.

Cuánto tarda

Normalmente 5–20 segundos desde el envío hasta el resultado; 2K e imagen a imagen son algo más lentos.

Llamadas reales de los últimos 7 días: mediana 14 s; el 90% termina en 18 s o menos.

Errores y reembolsos

Un error al enviar se devuelve al momento como HTTP 4xx / 5xx: no se crea ningún trabajo y no se cobra nada. Un fallo después de que el trabajo fue aceptado lo informa el endpoint del trabajo, y la retención se reembolsa íntegra. Todos los códigos están en Códigos de error.

Errores al enviar

Trabajos fallidos (status failed)

Webhooks en lugar de consultas

Añade callback_url al enviar y, en cuanto termine el trabajo, con éxito o con error, la pasarela enviará a esa URL exactamente lo mismo que devuelve el endpoint de consulta, firmado y con reintentos si la entrega falla. También puedes configurar una dirección para toda la cuenta en Configuración → Webhook, en la consola. Documentación de webhooks →

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image-quality", "prompt": "Un zorro rojo en un bosque nevado al amanecer, fotorrealista", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'