Grok 图片
使用 grok-imagine-image-2.0 编辑图片。
1 快速开始
使用 128 分组的 API Key。示例生成一张 1k 图片,保存并打开;按分组价格计费。代码已填入本站公开测试图,无需另备图片。 选下面一种方式运行即可,切换示例并重新发送会产生新的调用。
1.1 Python 3:完整流程
适用于 Windows、macOS 和 Linux。只使用 Python 标准库,无需安装 SDK。
将下面的代码保存为 grok-image-quickstart.py,在终端运行 python3 grok-image-quickstart.py(Windows 可用 py -3 grok-image-quickstart.py),按提示输入 API Key。程序会打印文件路径,并尝试用浏览器打开本地结果。
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 示例。如未自动打开结果,按输出路径手动打开。
1.2 PowerShell 7:完整流程
适合已有 PowerShell 7 的 Windows 用户。复制整段代码到终端,只按提示输入 API Key。
$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 Continue1.3 cURL / JSON:检查原始请求
JSON 是请求体,需要由 cURL、Postman 或 Apifox 发送。先将下面内容保存为 UTF-8 的 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 状态码。
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_KEYPostman / 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 接入信息与支持范围
本页覆盖已验证的图生图流程,需要 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 图生图:选择一种请求格式
接口: 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:单图或多图
保存为 grok-edit.json。单图只保留数组第一项;参考图使用可直接下载的 HTTPS 地址,或完整的 data URL。
{
"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.json3.2 multipart:本地图片
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.jsonmultipart 支持 PNG 双参考图;JSON 支持 JPEG/WebP 混合参考图。基础响应为 data[].b64_json;先解码,再按文件头确定 PNG/JPEG 扩展名。URL 方式需及时下载,下载请求使用明确的应用 User-Agent,不携带本站 API Key 到图片域名。
4 读取响应、保存与查看图片
请求 response_format="b64_json" 时,遍历 data 保存每张图片;下面只展示响应结构,Base64 是占位值。
{"data":[{"b64_json":"BASE64_IMAGE_DATA"}]}Base64 解码后按文件头选择 PNG / JPEG 扩展名,不能仅按请求的 output_format 命名。顶部 Python / PowerShell 示例已包含保存和打开图片的步骤。
选择 URL 输出时,读取 data[].url,先确认生成成功,再下载图片。下载请求使用明确的应用 User-Agent,不向图片域名发送本站 API Key。及时保存文件;本页不承诺统一的图片 URL 有效期。
5 参数限制与兼容差异
| 参数 | 推荐填写 | 支持结论 |
|---|---|---|
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 的重复引用测试成功,但推荐只传一种明确结构。文档示例使用已验证写法。官方编辑协议
6 比例与实际尺寸
以下为 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 常见错误与重试
- 400 :先看 JSON 字段名、数组结构、n 类型和必需参数。
- 422 :检查大小写与枚举值,优先恢复已验证的 low/medium、1k/2k 和明确比例。
- 502 且上游 403/1010 :检查请求 User-Agent、上游访问状态;这不是比例或参考图数量的证明。
- 生成 HTTP 200、图片下载 403 :图片已生成,先修复下载请求;不要直接重复生成。
- 超时/503 :先核对用量记录,等待通道恢复,再提交单图基线。不要连续重试相同大请求。
8 验证记录与能力边界
以下记录对应原文所标日期和测试样本,便于判断参数是否实际生效;不将未知字段被接受等同于功能已实现。
8.1 参考图数量与输出张数
| 项目 | 结果 |
|---|---|
| 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 编码与高级参数
| 项目 | 实际结果 |
|---|---|
| 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 与实际输出的对照
| 请求值 | 实际返回 |
|---|---|
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 并不保证锁定实际像素。本站兼容差异以上述测试记录为准。