Grok image-editing API · #128【YYY】Grok Imagine 2K

English translation. Model names, API fields and executable examples retain their original text, including prompts and comments.

Tip

New to the API? Start with the tutorial. Complete Your first image edit first, then return for #128【YYY】Grok Imagine 2K parameters, ratios and complete examples.

Important

Verified baseline: grok-imagine-image-2.0, one reference, aspect_ratio="1:1", resolution="1k", quality="low", n=1, response_format="b64_json". For production editing, move to medium and 2k one change at a time.

Site 2 · Updated: 2026-09-17. For new integrations, this guide recommends grok-imagine-image-2.0.

1. Connection and supported range

Starting request: one PNG, aspect_ratio="1:1", resolution="1k", quality="low", n=1, response_format="b64_json".

2. Effective parameters and reference formats

JSON structure: The site currently accepts images[].image_url. The official-style images[].url, top-level image:{"url":...} returned 400 at this site's gateway. Do not copy the official structure unchanged. Base64 needs a complete prefix such as data:image/png;base64,; bare Base64 returned 400 even in the correct field. image + images passed a duplicate-reference test, but use one unambiguous structure. The examples use verified syntax. Official editing protocol

Reference count versus output count

Descending result, 2026-09-17: counts 15 through 4 all returned HTTP 400 with an explicit maximum of three source images. Three references returned HTTP 200 and one 1024×1024 JPEG. The output retained numbers 1, 2 and 3 once each and added one blank quadrant.

Intermediate output counts were not tested individually and are not claimed as fully verified. Reference size and prompt complexity affect usability. These tests used small synthetic images and did not check single-file or total-request size limits.

Encoding and advanced parameters

seed, mask, output_compression, style, input_fidelity, moderation, partial_images, streaming and Files API uploads were not verified and are not listed as supported. Unknown fields were intentionally added to test permissive parsing; success does not imply that the field took effect.

3. Aspect ratios and actual dimensions

The following are all live Grok 2.0 image-editing tests with the same single reference, quality=medium and n=1. 1K / 2K name tiers, not a fixed longest side of 1024 / 2048. auto is the output of this sample, not a fixed size.

size comparison

Current live results show that stable settings should use aspect_ratio and resolution. Although local source code contains size conversion logic, that code was not treated as proof of live behavior. Consult the official reference for complete parameter descriptions; site-specific differences follow the tests above. Official aspect-ratio and quality reference

4. Editable request examples

JSON: one or multiple references

Save as grok-edit.json. For one reference, keep only the first array item. Use directly downloadable HTTPS image URLs or complete data URLs.

{
  "model": "grok-imagine-image-2.0",
  "prompt": "保留图1的主体，采用图2的配色，白色背景，保持主体结构",
  "images": [
    {"image_url": "https://YOUR_IMAGE_HOST/reference-1.png"},
    {"image_url": "data:image/jpeg;base64,YOUR_REFERENCE_2_BASE64"}
  ],
  "aspect_ratio": "16:9",
  "resolution": "2k",
  "quality": "medium",
  "n": 1,
  "response_format": "b64_json"
}

export YM2API_KEY="YOUR_GROUP_128_API_KEY"
curl --max-time 300 "https://yyds.seqnode.com/v1/images/edits" \
  -A "YM2API/1.0" \
  -H "Authorization: Bearer $YM2API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @grok-edit.json \
  -o response.json

Multipart: local images

curl --max-time 300 "https://yyds.seqnode.com/v1/images/edits" \
  -A "YM2API/1.0" \
  -H "Authorization: Bearer $YM2API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=保留图1的主体，采用图2的配色，白色背景" \
  -F "image=@reference-1.png" \
  -F "image=@reference-2.png" \
  -F "aspect_ratio=16:9" \
  -F "resolution=2k" \
  -F "quality=medium" \
  -F "n=1" \
  -F "response_format=b64_json" \
  -o response.json

This round verified multipart with two PNG references; mixed JPEG/WebP references passed through JSON. The baseline response uses data[].b64_json; decode it and detect PNG/JPEG from the file header. Download URL outputs promptly, using an explicit application User-Agent for downloads too. Do not send your site API key to the image host.

Troubleshooting order

1. 400: first check JSON field names, array structure, the type of n and required parameters.
2. 422: check casing and enum values; restore the verified low/medium, 1k/2k and explicit-ratio settings first.
3. 502 with upstream 403/1010: check the request User-Agent and upstream access. This is not evidence about aspect ratios or reference-count limits.
4. Generation HTTP 200, image download 403: the image was generated. Fix the download request before requesting another generation.
5. Timeout / 503: check usage records first, wait for channel recovery, then submit the single-image baseline. Do not repeatedly retry the same large request.

Complete verification results (Chinese source) · Adobe group debugging recommendations