# 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](getting-started.en.html) 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

| Item | Supported value |
| --- | --- |
| Group | #128 YYY Grok Imagine 2K |
| Recommended model | `grok-imagine-image-2.0` |
| Endpoint | `POST https://yyds.seqnode.com/v1/images/edits` |
| Authentication | `Authorization: Bearer YOUR_GROUP_128_API_KEY` |
| References | 1–3; JSON `images[].image_url` or multipart `image` |
| Resolution tiers | Lowercase `1k` / `2k` |
| Ratios | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `21:9`, `5:2`, `auto` |
| Quality | `low`, `medium`, `auto`; omission currently behaves like medium |
| Output count | Integer 1–10 |
| Response | `b64_json` or `url`; use an explicit application User-Agent to fetch URLs |

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

## 2. Effective parameters and reference formats

| Parameter | Recommended value | Site test result |
|----|----|----|
| `model` | `grok-imagine-image-2.0` | All detailed parameter tests on this page used this model |
| `prompt` | Clearly describe the edit and each reference's role | Required; an empty string returned 400 and omission returned 422. Prompt-length limits were not tested |
| `images` | `[{"image_url":"URL或data URL"}]` | **Up to 3 references**; PNG, mixed JPEG/WebP and HTTPS references succeeded. 4/5 references explicitly returned 400 |
| multipart `image` | Repeat uploads with the same field name | Two references succeeded; let cURL generate the multipart headers |
| `aspect_ratio` | One of the ratios below | Use an explicit ratio for a fixed frame;`auto` can produce varying ratios |
| `resolution` | Lowercase`"1k"` / `"2k"` | Both tiers were tested; uppercase`"2K"` returned 422. Do not rely on automatic correction |
| `size` | Prefer omission | Actual pixels did not lock to this value; even`size="2k"` is not equivalent to resolution=2k |
| `quality` | For debugging,`low`; for production editing, start with`medium` | `low` / `medium` / `auto` / omission all succeeded;`high` returned 400, explicitly allowing only low/medium/auto |
| `n` | Start debugging with numeric`1` | **Integer 1–10**, the number of output images. 2/3/10 returned the matching count; 11, 0, negative numbers and strings were rejected. 1.5 returned 422 |
| `response_format` | `"b64_json"` | Base64 responses decode directly; check URL generation and download status separately |
| `output_format` | Prefer omission | At 1K, png/jpeg/webp all returned JPEG; encoding did not switch |
| `background` | Prefer omission | transparent still returned JPEG; transparent output was not obtained |

**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](https://docs.x.ai/developers/model-capabilities/images/editing)

### Reference count versus output count

| Item         | Result                                               |
|--------------|------------------------------------------------------|
| 2 references | 1024×1024 JPEG                                       |
| 3 references | 1024×1024 JPEG                                       |
| 4 references | HTTP 400                                             |
| 5 references | HTTP 400                                             |
| `n=2`        | HTTP 200; 2 actual images, all decoded and verified  |
| `n=3`        | HTTP 200; 3 actual images, all decoded and verified  |
| `n=10`       | HTTP 200; 10 actual images, all decoded and verified |
| `n=11`       | HTTP 400; 0 actual images                            |
| `n=0`        | HTTP 400; 0 actual images                            |
| `n=-1`       | HTTP 400; 0 actual images                            |
| `n=1.5`      | HTTP 422; 0 actual images                            |

**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

| Item | Actual result |
|----|----|
| Two JPEG/WebP references | 1024×1024 JPEG |
| URL output + download with application User-Agent | 1024×1024 JPEG |
| Omit response_format + download with application User-Agent | 1024×1024 JPEG |
| output_format=png | 1024×1024 JPEG |
| output_format=jpeg | 1024×1024 JPEG |
| output_format=webp | 1024×1024 JPEG |
| background=transparent | 1024×1024 JPEG |

`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.

| Aspect ratio | 1K actual pixels / encoding | 2K actual pixels / encoding |
|--------------|-----------------------------|-----------------------------|
| `1:1`        | 1024×1024 JPEG              | 2048×2048 PNG               |
| `16:9`       | 1280×720 JPEG               | 2816×1584 PNG               |
| `9:16`       | 720×1280 JPEG               | 1584×2816 PNG               |
| `4:3`        | 1152×864 JPEG               | 2368×1776 PNG               |
| `3:4`        | 864×1152 JPEG               | 1776×2368 PNG               |
| `3:2`        | 1248×832 JPEG               | 2496×1664 PNG               |
| `2:3`        | 832×1248 JPEG               | 1664×2496 PNG               |
| `2:1`        | 1408×704 JPEG               | 2912×1456 PNG               |
| `1:2`        | 704×1408 JPEG               | 1456×2912 PNG               |
| `19.5:9`     | 1248×576 JPEG               | 2912×1344 PNG               |
| `9:19.5`     | 576×1248 JPEG               | 1344×2912 PNG               |
| `20:9`       | 1280×576 JPEG               | 3200×1440 PNG               |
| `9:20`       | 576×1280 JPEG               | 1440×3200 PNG               |
| `21:9`       | 1568×672 JPEG               | 3136×1344 PNG               |
| `5:2`        | 1600×640 JPEG               | 3200×1280 PNG               |
| `auto`       | 912×1136 JPEG               | 2368×1776 PNG               |

### size comparison

| Requested value | Actual result |
|----|----|
| `size="1024x1024"`, with ratio/tier omitted | 912×1136 JPEG |
| `size="1536x864"`, with ratio/tier omitted | 1248×832 JPEG |
| `size="864x1536"`, with ratio/tier omitted | 912×1136 JPEG |
| `size="3840x2160"`, with ratio/tier omitted | 1024×1024 JPEG |
| `size="auto"`, with ratio/tier omitted | 1280×720 JPEG |
| `size="2k"`, with ratio/tier omitted | 1248×832 JPEG |
| `size="864x1536"` + `aspect_ratio="16:9"` + `resolution="2k"` | 2816×1584 PNG |

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](https://docs.x.ai/developers/model-capabilities/images/generation)

## 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.

``` json
{
  "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"
}
```

``` bash
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

``` bash
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)](grok-imagine-image-test-report.md) · [Adobe group debugging recommendations](adobe-group127-api.en.html)