Imágenes con Grok Imagine

Genere y edite imágenes con Grok Imagine: parámetros, respuesta y advertencias.

Elemento	Valor
Base URL	`https://api.hop-base.com/v1`
Generar una imagen	`POST /v1/images/generations`
Editar una imagen	`POST /v1/images/edits`
Grupo	Grok gama completa

La generación de imágenes de Grok Imagine es solo síncrona: una solicitud devuelve un enlace de descarga temporal de la imagen.

Modelos disponibles

Modelo	ID de modelo	Niveles	Precio oficial
Grok Imagine Image	`grok-imagine-image`	`1k` / `2k`	$0,02/ imagen
Grok Imagine Image 2.0	`grok-imagine-image-2.0`	`1k` / `2k`	$0,04desde/ imagen
Grok Imagine Image Quality	`grok-imagine-image-quality`	`1k` / `2k`	$0,05desde/ imagen

Los tres modelos aceptan exactamente los mismos parámetros; solo cambia la tarifa.

Parámetros de la solicitud

Generación

Parámetro	Obligatorio	Tipo y límites	Predeterminado	Descripción
`model`	Obligatorio	string, uno de los tres ID	—	El ID que devuelve `GET /v1/models`
`prompt`	Obligatorio	string no vacío	—	Contenido, composición, estilo o edición
`resolution`	Opcional	`1k` / `2k`	`1k`	Nivel de píxeles y de facturación
`quality`	Opcional	`low` / `medium` / `auto`	`auto`	Parámetro propio de Grok
`aspect_ratio`	Opcional	16 valores, vea la tabla	`auto` (1:1)	Fija la forma
`n`	Opcional	entero 1–10	`1`	Se factura por imagen devuelta
`mask`	No admitido	—	—	Se rechaza con un 400

quality, aspect_ratio y n los comprueba el modelo, no la pasarela. grok-imagine-image-quality es un ID de modelo, no un valor del campo quality.

size es un parámetro de GPT Image y la generación de imágenes de Grok no lo usa: la forma la fija aspect_ratio y el nivel de píxeles lo fija resolution. Al migrar desde GPT Image: elimine size y ajuste quality a uno de los tres valores anteriores.

Edición

Además de los parámetros de generación, /v1/images/edits recibe las imágenes de referencia en image:

Parámetro	Obligatorio	Tipo y límites	Predeterminado	Descripción
`image`	Obligatorio	1–2 imágenes, URL o Data URL	—	Una tercera imagen se rechaza

image puede ser una cadena URL, un arreglo de cadenas o { "url": ... }.
Cada imagen es una URL HTTP(S) pública o una Data URL completa (data:image/png;base64,…).
No se admite base64 puro, asset:// ni file_id.
Subir un archivo local con el SDK de OpenAI también funciona, como image multipart o image[] repetidos.

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Cambie el fondo por una costa al atardecer, conserve el sujeto",
    "image": ["https://example.com/source.png"],
    "aspect_ratio": "3:2",
    "resolution": "1k"
  }'

Relación de aspecto y tamaño real de salida

aspect_ratio define la forma y resolution define el presupuesto de píxeles: cerca de 1 megapíxel en 1k y cerca de 4 megapíxeles en 2k. La tabla muestra los tamaños de salida medidos para grok-imagine-image con resolution: 1k:

`aspect_ratio`	Salida medida (1k)	Proporción
`1:1`	1024×1024	1.0000
`16:9`	1280×720	1.7778
`9:16`	720×1280	0.5625
`4:3`	1152×864	1.3333
`3:4`	864×1152	0.7500
`3:2`	1248×832	1.5000
`2:3`	832×1248	0.6667
`2:1`	1408×704	2.0000
`1:2`	704×1408	0.5000
`21:9`	1568×672	2.3333
`19.5:9`	1248×576	2.1667
`5:2`	1600×640	2.5000
`auto` / omitido	1024×1024	1.0000

9:19.5, 20:9 y 9:20 también son valores válidos; sencillamente no se listan arriba sus tamaños medidos. resolution: 2k mantiene la misma forma y aumenta el presupuesto de píxeles: 16:9 pasa a 2816×1584 y 1:1 a 2048×2048.

Respuesta

Campo	Tipo	Descripción
`data`	array	Imágenes generadas, una por imagen devuelta
`data[].url`	string	Enlace de descarga temporal de la imagen
`usage.cost_in_usd_ticks`	integer	Medición oficial, no su cargo

Ejemplo de respuesta (URL ilustrativa; otros metadatos omitidos):

{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

Descargue y guarde la imagen en cuanto la reciba. La respuesta no incluye uso de tokens; una respuesta vacía significa que no se generó ninguna imagen, así que un arreglo data vacío no es un éxito.

Ejemplos

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Gato naranja dormido en un alféizar soleado, foto de revista",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

aspect_ratio y resolution no son parámetros integrados del SDK de OpenAI, así que en Python van en extra_body.

Advertencias

Solo síncrono: no hay streaming y no debe enviar Prefer: respond-async.
En imagen, resolution solo admite 1k o 2k: no hay nivel 4K y los valores de video 480p / 720p / 1080p no sirven.
La URL devuelta es temporal, así que descargue la imagen de inmediato.
La edición admite como máximo 2 imágenes de referencia; es un límite de HopBase para imágenes y no aplica al video.
Imagen y video son dos grupos distintos y las claves no sirven de uno a otro; para video, vea Video de Grok Imagine.

Errores comunes

Error	Solución
`resolution must be 1k or 2k`	Use `1k` o `2k`
`this model does not support the mask parameter`	Quite `mask`
`this model supports at most 2 input images on /v1/images/edits`	Envíe 2 imágenes de referencia o menos
`prompt must not be empty`	Envíe un `prompt` no vacío
`/v1/images/edits requires at least one image`	Envíe 1–2 imágenes en `image`
`image must be a data URL or an http(s) URL`	Convierta el base64 puro en una Data URL completa
`image object is missing the url field`	Escriba el objeto como `{ "url": ... }`
`image models do not support Chat Completions, please use the Images API`	Llame a `/v1/images/generations`
400 con `content-moderated` en el mensaje	Reformule el prompt; no se factura

Los valores fuera de rango de n, quality o aspect_ratio los rechaza el modelo con su propio mensaje. Cuando una solicitud de imagen falla, revise el estado HTTP y error.

Facturación

El cobro es por imagen devuelta y por nivel de resolution, nunca por las dimensiones en píxeles; cada imagen de referencia en /v1/images/edits se cobra aparte y las solicitudes moderadas no se facturan. grok-imagine-image también acepta 2k y lo factura a la tarifa de 1k.

El campo usage.cost_in_usd_ticks de la respuesta no es su cargo; concilie con la página Consumo de la consola. Las tarifas por nivel están en las fichas de modelo de arriba, y su tarifa es la que aparece en la Plaza de modelos.

Próximos pasos

Resumen de imágenes: compare las series de imagen y las reglas comunes
GPT Image, imágenes de Gemini, Seedream: otras series de imagen
Video de Grok Imagine: envíe y consulte tareas de video de Grok
Referencia de API: Generar imágenes, Editar imágenes
Solución de problemas: diagnostique solicitudes fallidas por síntoma

Más detalles

En esta página