Grok Imagine images

Grok Imagine image generation is synchronous only: one request returns a temporary download link for the image.

Available models

The three models take exactly the same request parameters; only the rates differ.

Request parameters

Generations

quality, aspect_ratio, and n are checked by the model, not the gateway. grok-imagine-image-quality is a model ID, not a value of the quality field.

size is a GPT Image parameter and Grok image generation does not use it: shape comes from aspect_ratio and the pixel tier from resolution. Migrating from GPT Image: drop size, and map quality onto one of the three values above.

Edits

On top of the generation parameters, /v1/images/edits takes reference images in image:

• image can be a URL string, a string array, or { "url": ... }.
• Each image is a public HTTP(S) URL or a full Data URL (data:image/png;base64,…).
• Bare base64, asset://, and file_id are not accepted.
• Uploading a local file with the OpenAI SDK works too, as a multipart image or repeated image[] files.

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Replace the background with a seaside at dusk, keep the subject",
    "image": ["https://example.com/source.png"],
    "aspect_ratio": "3:2",
    "resolution": "1k"
  }'

Aspect ratio and actual output size

aspect_ratio sets the shape and resolution sets the pixel budget: about 1 megapixel at 1k and about 4 megapixels at 2k. The table shows measured output sizes for grok-imagine-image at resolution: 1k:

9:19.5, 20:9, and 9:20 are also valid values; their measured sizes are simply not listed above. resolution: 2k keeps the same shape and raises the pixel budget — 16:9 becomes 2816×1584 and 1:1 becomes 2048×2048.

Response

Example response (placeholder URL; other metadata omitted):

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

Download and store the image as soon as you receive it. The response carries no token usage; an empty response means no image was generated, so an empty data array is not a success.

Examples

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "An orange cat asleep on a sunlit windowsill, magazine photo",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

aspect_ratio and resolution are not built-in OpenAI SDK parameters, so Python passes them in extra_body.

Caveats

• Synchronous only: there is no streaming, and do not send Prefer: respond-async.
• Image resolution is 1k or 2k only — no 4K tier, and the video values 480p / 720p / 1080p do not apply.
• The returned URL is temporary, so download the image right away.
• Edits take at most 2 reference images; this is HopBase's image-edit limit and does not apply to video.
• Images and video are two separate groups and keys do not cross over; for video see Grok Imagine video.

Common errors

Out-of-range n, quality, or aspect_ratio values are rejected by the model with its own message. When an image request fails, check the HTTP status and error.

Billing

Charges are per image returned, by resolution tier, never by pixel dimensions; each reference image on /v1/images/edits is charged separately, and moderated requests are not billed. grok-imagine-image also accepts 2k and bills it at the 1k rate.

The usage.cost_in_usd_ticks field in the response is not your charge; reconcile against the Usage page in the console. Per-tier rates are on the model cards above, and your own rate is the one in the Model Plaza.

Next steps

• Image overview: compare image series and shared rules
• GPT Image, Gemini image, Seedream: other image series
• Grok Imagine video: submit and poll Grok video tasks
• API reference: Create image, Edit image
• Troubleshooting: diagnose failed requests by symptom