# Grok 图片 {#grok-图生图接口文档--128yyygrok-imagine-2k .rd-guide-title} 使用 `grok-imagine-image-2.0` 编辑图片。 ## 1 快速开始 {#quickstart} 使用 **128 分组**的 API Key。示例生成一张 **1k** 图片，保存并打开；按分组价格计费。代码已填入本站公开测试图，无需另备图片。 选下面一种方式运行即可，切换示例并重新发送会产生新的调用。 ### 1.1 Python 3：完整流程 {#quick-python} 适用于 Windows、macOS 和 Linux。只使用 Python 标准库，无需安装 SDK。 将下面的代码保存为 `grok-image-quickstart.py`，在终端运行 `python3 grok-image-quickstart.py`（Windows 可用 `py -3 grok-image-quickstart.py`），按提示输入 API Key。程序会打印文件路径，并尝试用浏览器打开本地结果。 ``` python import base64 import getpass import json from pathlib import Path from urllib.error import HTTPError from urllib.request import Request, urlopen import uuid import webbrowser URL = 'https://yyds.seqnode.com/v1/images/edits' PAYLOAD = { "model": "grok-imagine-image-2.0", "prompt": "保留参考图的主体布局，将背景改为浅蓝色，增加柔和光线。", "images": [ { "image_url": "https://yyds.seqnode.com/api-docs/parameter-test-fixtures/1.png" } ], "aspect_ratio": "1:1", "resolution": "1k", "quality": "low", "n": 1, "response_format": "b64_json" } def main(): api_key = getpass.getpass("输入 API Key：").strip() if not api_key: raise ValueError("请输入有效的 API Key。") headers = {"Authorization": "Bearer " + api_key} headers["Content-Type"] = "application/json; charset=utf-8" headers["User-Agent"] = "YM2API-Quickstart/1.0" request = Request(URL, data=json.dumps(PAYLOAD, ensure_ascii=False).encode("utf-8"), headers=headers) with urlopen(request, timeout=300) as response: result = json.load(response) encoded = next((item["b64_json"] for item in result.get("data", []) if item.get("b64_json")), None) if not encoded: raise ValueError("响应没有最终图片。请检查响应和使用记录，再决定是否重试。") data = base64.b64decode(encoded, validate=True) if data.startswith(b"\x89PNG\r\n\x1a\n"): extension = ".png" elif data.startswith(b"\xff\xd8\xff"): extension = ".jpg" elif len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP": extension = ".webp" else: raise ValueError("返回数据不是可识别的 PNG、JPEG 或 WebP。") path = Path.cwd() / ("grok-image-" + uuid.uuid4().hex + extension) with path.open("xb") as output: output.write(data) print(f"图片已保存：{path}") if not webbrowser.open(path.as_uri()): print("请到以上路径手动打开图片。") if __name__ == "__main__": try: main() except HTTPError as error: print(f"HTTP {error.code}：{error.read(2000).decode('utf-8', errors='replace')}") raise SystemExit(1) except Exception as error: print(f"运行失败：{error}") raise SystemExit(1) ``` [下载 Python 示例](grok-image-quickstart.py)。如未自动打开结果，按输出路径手动打开。 ### 1.2 PowerShell 7：完整流程 {#quick-powershell} 适合已有 PowerShell 7 的 Windows 用户。复制整段代码到终端，只按提示输入 API Key。 ``` powershell $apiKey = Read-Host "输入 API Key" -MaskInput if ([string]::IsNullOrWhiteSpace($apiKey)) { throw "请输入有效的 API Key。" } $payload = @{ model = "grok-imagine-image-2.0" prompt = "保留参考图的主体布局，将背景改为浅蓝色，增加柔和光线。" images = @(@{ image_url = "https://yyds.seqnode.com/api-docs/parameter-test-fixtures/1.png" }) aspect_ratio = "1:1" resolution = "1k" quality = "low" n = 1 response_format = "b64_json" } $request = @{ Uri = "https://yyds.seqnode.com/v1/images/edits" Method = "Post" Headers = @{ Authorization = "Bearer $apiKey"; "User-Agent" = "YM2API-Quickstart/1.0" } ContentType = "application/json; charset=utf-8" Body = [Text.Encoding]::UTF8.GetBytes(($payload | ConvertTo-Json -Depth 12)) TimeoutSec = 300 ErrorAction = "Stop" } $result = Invoke-RestMethod @request $image = $result.data | Where-Object { $_.b64_json } | Select-Object -First 1 if (-not $image) { throw "响应中没有 b64_json 图片。请保留响应和使用记录排查。" } $bytes = [Convert]::FromBase64String($image.b64_json) # 根据文件头识别格式，避免把 JPEG 保存为 PNG。 if ($bytes.Length -lt 12) { throw "返回的图片数据过短。请保留响应排查。" } $hex = [BitConverter]::ToString($bytes, 0, 12).Replace("-", "") $extension = if ($hex.StartsWith("89504E470D0A1A0A")) { ".png" } elseif ($hex.StartsWith("FFD8FF")) { ".jpg" } elseif ($bytes.Length -ge 12 -and [Text.Encoding]::ASCII.GetString($bytes, 0, 4) -eq "RIFF" -and [Text.Encoding]::ASCII.GetString($bytes, 8, 4) -eq "WEBP") { ".webp" } else { throw "返回数据不是可识别的 PNG、JPEG 或 WebP。请保留响应排查。" } $file = Join-Path $PWD ("grok-image-" + [guid]::NewGuid().ToString("N") + $extension) $stream = [IO.File]::Open($file, [IO.FileMode]::CreateNew) try { $stream.Write($bytes, 0, $bytes.Length) } finally { $stream.Dispose() } Write-Host "图片已保存：$file" Invoke-Item -LiteralPath $file -ErrorAction Continue ``` [下载 PowerShell 示例](grok-image-quickstart.ps1)。 ### 1.3 cURL / JSON：检查原始请求 {#quick-http} JSON 是请求体，需要由 cURL、Postman 或 Apifox 发送。先将下面内容保存为 UTF-8 的 `grok-image-request.json`，也可[下载请求 JSON](grok-image-request.json)。 ``` json { "model": "grok-imagine-image-2.0", "prompt": "保留参考图的主体布局，将背景改为浅蓝色，增加柔和光线。", "images": [ { "image_url": "https://yyds.seqnode.com/api-docs/parameter-test-fixtures/1.png" } ], "aspect_ratio": "1:1", "resolution": "1k", "quality": "low", "n": 1, "response_format": "b64_json" } ``` 在该文件所在目录，用 Bash（Linux、macOS 或 Git Bash）运行下面的命令，只输入 API Key。响应保存到 `response.json`，已有同名文件会被覆盖；终端显示 HTTP 状态码。 ``` bash read -rsp 'API Key: ' API_KEY; printf '\n' curl --silent --show-error --fail-with-body --max-time 300 "https://yyds.seqnode.com/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -H 'Content-Type: application/json' \ --data-binary '@grok-image-request.json' \ --output response.json --write-out 'HTTP %{http_code}\n' unset API_KEY ``` Postman / Apifox：新建 **POST** 请求，URL 填 `https://yyds.seqnode.com/v1/images/edits`，Body 选择 **raw → JSON** 并粘贴上面的 JSON；请求头设置 `Content-Type: application/json` 和 `Authorization: Bearer YOUR_API_KEY`，将 `YOUR_API_KEY` 替换为自己的 Key。 HTTP 200 后，还需确认响应包含图片数据。cURL 保存的是 JSON；Python 和 PowerShell 示例会自动解码并保存图片。 ## 2 接入信息与支持范围 {#section-1} 本页覆盖已验证的图生图流程，需要 1--3 张参考图。先跑通顶部示例，再选择 JSON 或文件上传；不把未验证的文生图接口列为可用场景。 项目 支持值 ---------- ---------------------------------------------------------------------------------------------------------------------------- 分组 #128【YYY】Grok Imagine 2K 推荐模型 `grok-imagine-image-2.0` 端点 `POST https://yyds.seqnode.com/v1/images/edits` 鉴权 `Authorization: Bearer YOUR_GROUP_128_API_KEY` 参考图 1～3 张；JSON `images[].image_url` 或 multipart `image` 分辨率档 小写 `1k` / `2k` 比例 `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` 质量 `low`、`medium`、`auto`；省略等同当前 medium 行为 输出数量 整数 1～10 返回 `b64_json` 或 `url`；URL 下载请求使用明确的应用 User-Agent 推荐起点：单张 PNG、`aspect_ratio="1:1"`、`resolution="1k"`、`quality="low"`、`n=1`、`response_format="b64_json"`。 ## 3 图生图：选择一种请求格式 {#section-7} **接口：** `POST /v1/images/edits`。两种格式的生成参数相同，区别在于参考图如何提交。 ---------------------------------------------------------------------------------------------------- 参数 填写要求 示例 / 说明 --------------------------------- ----------------------- ------------------------------------------ `model` 填写 `grok-imagine-image-2.0` `prompt` 填写 描述编辑目标 `images[].image_url` 或 `image` 选择一种 JSON 使用 URL / Data URL；表单使用文件 `resolution` 推荐显式填写 小写 `1k` 或 `2k` `aspect_ratio` 推荐显式填写 如 `1:1`；精确像素见尺寸表 `n` 调试填写数字 `1` 输出图片数量 `response_format` 推荐 `b64_json` 解码后保存；避免将生成成功与下载成功混淆 ---------------------------------------------------------------------------------------------------- ### 3.1 JSON：单图或多图 {#section-8} 保存为 `grok-edit.json`。单图只保留数组第一项；参考图使用可直接下载的 HTTPS 地址，或完整的 data URL。 ``` 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 ``` ### 3.2 multipart：本地图片 {#section-9} ``` 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 ``` multipart 支持 PNG 双参考图；JSON 支持 JPEG/WebP 混合参考图。基础响应为 `data[].b64_json`；先解码，再按文件头确定 PNG/JPEG 扩展名。URL 方式需及时下载，下载请求使用明确的应用 User-Agent，不携带本站 API Key 到图片域名。 ## 4 读取响应、保存与查看图片 {#grok-response} 请求 `response_format="b64_json"` 时，遍历 `data` 保存每张图片；下面只展示响应结构，Base64 是占位值。 ``` json {"data":[{"b64_json":"BASE64_IMAGE_DATA"}]} ``` Base64 解码后按文件头选择 PNG / JPEG 扩展名，不能仅按请求的 `output_format` 命名。顶部 Python / PowerShell 示例已包含保存和打开图片的步骤。 选择 URL 输出时，读取 `data[].url`，先确认生成成功，再下载图片。下载请求使用明确的应用 User-Agent，不向图片域名发送本站 API Key。及时保存文件；本页不承诺统一的图片 URL 有效期。 ## 5 参数限制与兼容差异 {#section-2} 参数 推荐填写 支持结论 ------------------- ----------------------------------- ------------------------------------------------------------------------------------------------ `model` `grok-imagine-image-2.0` 本页全部详细参数测试使用此模型 `prompt` 清楚描述编辑目标及每张参考图用途 必填；空字符串返回 400，省略返回 422；提示词长度上限未测 `images` `[{"image_url":"URL或data URL"}]` **最多 3 张** ；PNG、JPEG/WebP 混合、HTTPS 参考图成功；4/5 张明确返回 400 multipart `image` 重复上传同名字段 双参考图成功；让 cURL 自动生成 multipart 请求头 `aspect_ratio` 下表比例之一 固定画幅使用明确比例；`auto` 的实际画幅会变化 `resolution` 小写 `"1k"` / `"2k"` 两档实测；大写 `"2K"` 返回 422，勿依赖自动纠正 `size` 推荐省略 实际像素未按请求锁定；即使 `size="2k"` 也不等于 resolution=2k `quality` 调试 `low`，正式编辑起点 `medium` `low` / `medium` / `auto` / 省略均成功；`high` 返回 400，明确仅允许 low/medium/auto `n` 调试先用数字 `1` **整数 1～10** ，表示输出张数；2/3/10 返回对应数量，11、0、负数、字符串被拒；小数 1.5 返回 422 `response_format` `"b64_json"` 返回 Base64 可直接解码；URL 生成状态和下载状态分别检查 `output_format` 推荐省略 1K 下 png/jpeg/webp 三种值都返回 JPEG，未实现编码切换 `background` 推荐省略 transparent 实测仍返回 JPEG，未得到透明输出 **JSON 结构注意：** 当前本站接受 `images[].image_url`。官方风格 `images[].url`、顶层 `image:{"url":...}` 在本站入口返回 400；不要直接复制官方结构到本站。Base64 必须带 `data:image/png;base64,` 等完整前缀；裸 Base64 在正确字段下也返回 400。`image + images` 的重复引用测试成功，但推荐只传一种明确结构。文档示例使用已验证写法。[官方编辑协议](https://docs.x.ai/developers/model-capabilities/images/editing) ## 6 比例与实际尺寸 {#section-5} 以下为 **2026-09-15 Grok 2.0 图生图结果** ，相同单参考图，quality=medium、n=1。1K / 2K 是档位名称，并非最长边固定为 1024 / 2048。`auto` 是本次样本，不是固定尺寸。 比例 1K 实际像素 / 编码 2K 实际像素 / 编码 ---------- -------------------- -------------------- `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 ## 7 常见错误与重试 {#section-10} 1. **400** ：先看 JSON 字段名、数组结构、n 类型和必需参数。 2. **422** ：检查大小写与枚举值，优先恢复已验证的 low/medium、1k/2k 和明确比例。 3. **502 且上游 403/1010** ：检查请求 User-Agent、上游访问状态；这不是比例或参考图数量的证明。 4. **生成 HTTP 200、图片下载 403** ：图片已生成，先修复下载请求；不要直接重复生成。 5. **超时/503** ：先核对用量记录，等待通道恢复，再提交单图基线。不要连续重试相同大请求。 [日期化支持矩阵](grok-imagine-image-test-report.md) · [Adobe 分组调用建议](adobe-group127-api.html) ## 8 验证记录与能力边界 {#grok-validation} 以下记录对应原文所标日期和测试样本，便于判断参数是否实际生效；不将未知字段被接受等同于功能已实现。 ### 8.1 参考图数量与输出张数 {#section-3} 项目 结果 ------------ -------------------------------------------- 2 张参考图 1024×1024 JPEG 3 张参考图 1024×1024 JPEG 4 张参考图 HTTP 400 5 张参考图 HTTP 400 `n=2` HTTP 200；实际返回 2 张，全部解码校验通过 `n=3` HTTP 200；实际返回 3 张，全部解码校验通过 `n=10` HTTP 200；实际返回 10 张，全部解码校验通过 `n=11` HTTP 400；实际返回 0 张 `n=0` HTTP 400；实际返回 0 张 `n=-1` HTTP 400；实际返回 0 张 `n=1.5` HTTP 422；实际返回 0 张 **2026-09-17 递减结果：** 15～4 张参考图全部返回 HTTP 400，错误明确为最多 3 张源图；3 张返回 HTTP 200 和一张 1024×1024 JPEG。成图保留编号 1、2、3，各一次，并额外出现一个空白象限。 ### 8.2 编码与高级参数 {#section-4} 项目 实际结果 --------------------------------------------- ---------------- JPEG/WebP 双参考图 1024×1024 JPEG URL 输出 + 应用 User-Agent 下载 1024×1024 JPEG 省略 response_format + 应用 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`、流式响应和 Files API 上传不在当前已确认支持范围内。未知字段即使未被拒绝，也不表示字段生效。 ### 8.3 size 与实际输出的对照 {#section-6} 请求值 实际返回 --------------------------------------------------------------- ---------------- `size="1024x1024"`，省略比例/档位 912×1136 JPEG `size="1536x864"`，省略比例/档位 1248×832 JPEG `size="864x1536"`，省略比例/档位 912×1136 JPEG `size="3840x2160"`，省略比例/档位 1024×1024 JPEG `size="auto"`，省略比例/档位 1280×720 JPEG `size="2k"`，省略比例/档位 1248×832 JPEG `size="864x1536"` + `aspect_ratio="16:9"` + `resolution="2k"` 2816×1584 PNG 设置画幅时使用 aspect_ratio 与 resolution；size 并不保证锁定实际像素。本站兼容差异以上述测试记录为准。