Start with your first image

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

This tutorial uses the group #128【YYY】Grok Imagine 2K with model grok-imagine-image-2.0 to complete an image edit through four steps: prepare → request → inspect → debug.

Important

Check your group first. Use the key for #128【YYY】Grok Imagine 2K. Parameters and prices may differ for same-name models in other groups. This guide does not ask you to enter your key into the webpage.

1. Prepare your key and a reference

Prepare Python 3, a terminal and a reference.png image in a new folder. Start with one ordinary PNG; leave complex multi-image layouts until the baseline request succeeds.

Description

Use your site bill as the source of truth. A lower upstream billing metric for low does not guarantee a lower site charge. Each generation may be billed; do not repeatedly submit the same failing request.

2. Build the request file

Save the following as make_request.py. Comments belong in the Python script; the generated request.json is strict JSON without comments.

import base64
import json
from pathlib import Path

image = Path("reference.png").read_bytes()  # 与脚本放在同一文件夹
payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": "保留参考图中的主体和主要颜色，改成简洁白色背景",
    "images": [{
        "image_url": "data:image/png;base64," + base64.b64encode(image).decode()
    }],
    "aspect_ratio": "1:1",      # 调试时先固定画幅
    "resolution": "1k",        # 必须使用小写 1k / 2k
    "quality": "low",          # 正式编辑可调整到 medium
    "n": 1,                    # 输出张数，不是参考图数量
    "response_format": "b64_json"
}
Path("request.json").write_text(
    json.dumps(payload, ensure_ascii=False), encoding="utf-8"
)
print("request.json 已生成")

In your terminal, run python make_request.py. You should see request.json 已生成 and find the request file in the current folder.

Tip

Change the prefix when changing image format. For JPEG use data:image/jpeg;base64,, and for WebP use data:image/webp;base64,. Do not paste bare Base64 or rename the field to images[].url.

3. Send one request

Replace the example key with your own. Run the block for your terminal; you do not need to run both.

Bash / WSL / macOS

export YM2API_KEY="YOUR_GROUP_128_API_KEY"
python make_request.py
curl --fail-with-body --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 @request.json \
  -D response.headers \
  -o response.json

Windows PowerShell

$env:YM2API_KEY = "YOUR_GROUP_128_API_KEY"
python make_request.py
curl.exe --fail-with-body --max-time 300 "https://yyds.seqnode.com/v1/images/edits" -A "YM2API/1.0" -H "Authorization: Bearer $env:YM2API_KEY" -H "Content-Type: application/json" --data-binary "@request.json" -D response.headers -o response.json

Checkpoint: Creates response.headers and response.json. The response headers should contain HTTP 200, and the JSON should contain a nonempty data array. If you see error, follow section 6 before resubmitting.

Watch out

Distinguish generation failures from download failures. The default Python User-Agent triggered upstream 403 / Cloudflare 1010 during testing. These examples set YM2API/1.0. URL responses require a separate download. A download failure does not mean generation failed or that no charge occurred.

4. Save and inspect the image

Save the following as save_images.py and run python save_images.py. This processes only the local response file and does not create a new generation request.

import base64
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8"))
if response.get("error"):
    raise SystemExit(json.dumps(response["error"], ensure_ascii=False))
items = response.get("data", [])
if not items:
    raise SystemExit("没有图片数据，请检查响应和用量记录")
for i, item in enumerate(items, 1):
    if not item.get("b64_json"):
        raise SystemExit("没有 b64_json；请先检查 response_format 与原始响应")
    raw = base64.b64decode(item["b64_json"], validate=True)
    if raw.startswith(b"\x89PNG\r\n\x1a\n"):
        ext = "png"
    elif raw.startswith(b"\xff\xd8"):
        ext = "jpg"
    elif raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
        ext = "webp"
    else:
        raise SystemExit("返回内容不是已识别的图片编码")
    path = Path(f"result-{i}.{ext}")
    if path.exists():
        raise SystemExit(f"{path} 已存在，请先改名保存，避免覆盖")
    path.write_bytes(raw)
    print(f"已保存 {path}，{len(raw)} 字节")

Checkpoint: Open the result and check the reference subject, orientation, actual dimensions and image count. Grok's 1:1 + 1k produced a 1024×1024 JPEG in tests. For other ratios, see the Grok ratio table.

5. Change one parameter at a time

After each change to make_request.py, regenerate request.json and submit once. Record the single change you made.

Important

Stable Grok configuration: aspect_ratio controls the aspect ratio, and resolution controls the 1k/2k tier. Do not rely on size for exact pixel dimensions. high, uppercase 2K and 4k did not pass. The site currently allows up to 3 references and n up to 10.

Specify multi-image layouts explicitly, for example: “Arrange the three references in one row, each appearing once.” The three-reference test retained all three numbers but added an empty cell, so inspect the layout manually.

Switching to the Adobe group

#127【YYY】4k Image 2.0 (Med) 4K image2.5 flare / sunburst Start with gpt-image-2, size="1536x864", quality="medium", n=1. Its size parameters differ from Grok's. Switch to the group's key and follow the full request in the Adobe API guide rather than carrying Grok parameters across unchanged.

6. Debug by failure stage

Keep these details for troubleshooting: group name, model, time, HTTP status, error body, parameters and actual dimensions. Remove keys, Authorization headers and private image content before sharing logs.

7. Further reading

• #128【YYY】Grok Imagine 2K: parameters, all ratios and a report covering 93 requests.
• #127 Adobe image group: 10/6-reference boundaries, 4K tests and model differences.
• #75 Upscaling / #77 Integration: dimensions and proxy behavior for these groups.

Description

The request structures are based on earlier live tests. This documentation update did not send additional paid generation requests. Code examples passed syntax and local-sample checks.