Skip to content

Grok Imagine images

Generate and edit images with Grok Imagine: parameters, responses, and caveats.

ItemValue
Base URLhttps://api.hop-base.com/v1
Generate an imagePOST /v1/images/generations
Edit an imagePOST /v1/images/edits
GroupGrok Suite

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

Available models

ModelModel IDTiersOfficial price
Grok Imagine Imagegrok-imagine-image1k / 2k$0.02/ image
Grok Imagine Image 2.0grok-imagine-image-2.01k / 2k$0.04from/ image
Grok Imagine Image Qualitygrok-imagine-image-quality1k / 2k$0.05from/ image

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

Request parameters

Generations

ParameterRequiredType and limitsDefaultDescription
modelRequiredstring, one of the three IDs above—Use the ID GET /v1/models returns
promptRequiredstring, non-empty—Content, composition, style, or edit
resolutionOptional1k / 2k1kPixel tier and billing tier
qualityOptionallow / medium / autoautoGrok's own parameter
aspect_ratioOptional16 values, see the size tableauto (1:1)Sets the shape
nOptionalinteger 1–101Billed per image actually returned
maskNot supported——Rejected with 400

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:

ParameterRequiredType and limitsDefaultDescription
imageRequired1–5 images (Quality: 1–3), URL or Data URL—Extra images are rejected
  • image can be a URL string, a string array, or { "url": ... }; xAI's native images ([{ "url": ... }]) also works.
  • 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:

aspect_ratioMeasured output (1k)Ratio
1:11024×10241.0000
16:91280×7201.7778
9:16720×12800.5625
4:31152×8641.3333
3:4864×11520.7500
3:21248×8321.5000
2:3832×12480.6667
2:11408×7042.0000
1:2704×14080.5000
21:91568×6722.3333
19.5:91248×5762.1667
5:21600×6402.5000
auto / omitted1024×10241.0000

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

FieldTypeDescription
dataarrayGenerated images, one per image returned
data[].urlstringTemporary download link for the image
usage.cost_in_usd_ticksintegerOfficial metering value at the official USD price, in units of one ten-billionth of a dollar, passed through unchanged; not your charge
usage.costnumberThe charge for this request in CNY (after your group's rate; the same charge as usage.cost_usd), up to 6 decimal places
usage.cost_usdnumberThe USD amount actually deducted from your balance, up to 8 decimal places, the same amount as this request's usage record
usage.currencystringThe currency of usage.cost, always CNY

Example response (placeholder URL; other metadata omitted):

{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ],
  "usage": {
    "cost_in_usd_ticks": 200000000,
    "cost": 0.0816,
    "cost_usd": 0.012,
    "currency": "CNY"
  }
}

The same charge is also sent in the response headers X-HopBase-Cost, X-HopBase-Cost-USD, and X-HopBase-Currency. When generation takes longer than about 40 seconds, HopBase sends the 200 headers first and writes whitespace keep-alives, so the headers carry no charge; reconcile against usage.cost_usd (USD, matching your usage record) or usage.cost (CNY) in the body. Failures that are not charged carry none of these fields. See Charges.

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.
  • The edit reference-image limit depends on the model: up to 5 for grok-imagine-image and grok-imagine-image-2.0, up to 3 for grok-imagine-image-quality; this does not apply to video.
  • Images and video are two separate groups; a key reaches video only if it also includes the Grok Video group. For video see Grok Imagine video.

Common errors

ErrorFix
resolution must be 1k or 2kUse 1k or 2k
this model does not support the mask parameterRemove mask
<model> accepts at most N reference images per edit, got M; remove K and try againSend N reference images or fewer (3 for Quality, 5 otherwise)
prompt must not be emptySend a non-empty prompt
/v1/images/edits requires at least one reference image: send "image" ... or "images" ...Send reference images in image or images (1–3 for Quality, 1–5 otherwise)
image must be a data URL or an http(s) URLWrap bare base64 in a full Data URL
image object is missing the url fieldWrite the object as { "url": ... }
image models do not support Chat Completions, please use the Images APICall /v1/images/generations instead
400 with content-moderated in the messageRephrase the prompt; not billed

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 the official USD metering and is not your charge; usage.cost_usd is the amount actually deducted from your balance for this request (in USD), and usage.cost is the same charge in CNY. Do not treat the official metering as your charge: reconcile against usage.cost_usd or 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