YM2API开发者文档
跳到正文
文档 / Grok 图片下载 Markdown ↓

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 Continue

下载 PowerShell 示例。

1.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_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 接入信息与支持范围

本页覆盖已验证的图生图流程,需要 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.json

3.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.json

multipart 支持 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 常见错误与重试

  1. 400 :先看 JSON 字段名、数组结构、n 类型和必需参数。
  2. 422 :检查大小写与枚举值,优先恢复已验证的 low/medium、1k/2k 和明确比例。
  3. 502 且上游 403/1010 :检查请求 User-Agent、上游访问状态;这不是比例或参考图数量的证明。
  4. 生成 HTTP 200、图片下载 403 :图片已生成,先修复下载请求;不要直接重复生成。
  5. 超时/503 :先核对用量记录,等待通道恢复,再提交单图基线。不要连续重试相同大请求。

日期化支持矩阵 · Adobe 分组调用建议

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 并不保证锁定实际像素。本站兼容差异以上述测试记录为准。