YM2API开发者文档
跳到正文
文档 / 第一次图生图下载 Markdown ↓

从第一张图片开始

本教程使用 #128【YYY】Grok Imagine 2K 的 grok-imagine-image-2.0,按“准备 → 请求 → 检查 → 调试”的顺序完成一次图生图。

Important

先确认分组。 使用 #128【YYY】Grok Imagine 2K 的 Key。其他分组同名模型的参数与价格可能不同;本文不会要求你把 Key 填进网页。

1. 准备 Key 和一张参考图

准备 Python 3、终端和一张 reference.png,把图片放进新文件夹。先使用单张普通 PNG,把复杂多图排版留到基础请求成功后。

项目 第一次建议 为什么
模型 grok-imagine-image-2.0 当前文档统一推荐入口
参考图 1 张 PNG 先确认输入确实进入生成结果
比例 / 档位 1:1 / 1k 便于观察尺寸和输出内容
质量 / 张数 low / 1 单图容易排错;low 的上游计费指标较低
返回格式 b64_json 省去独立下载图片 URL 的步骤

Note

价格以本站账单为准。 low 的上游计费指标较低,不等于本站一定按更低单价扣费。每次生成都可能计费,不要反复提交同一个失败请求。

2. 生成请求文件

将下面保存为 make_request.py。注释放在 Python 中;生成的 request.json 是严格 JSON,不含注释。

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 已生成")

在终端运行 python make_request.py。应看到 request.json 已生成,并在当前文件夹找到请求文件。

Tip

修改图片格式时一起修改前缀。 JPEG 用 data:image/jpeg;base64,,WebP 用 data:image/webp;base64,。不要只粘贴裸 Base64,也不要把字段改成 images[].url。

3. 发送一次请求

把示例 Key 替换为自己的 Key。选择与你的终端对应的一段运行;不需要把两段都执行。

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

检查点: 生成 response.headers 与 response.json。响应头应包含 HTTP 200,JSON 应包含非空 data 数组。如果有 error,先按第 6 节处理,不要直接重发。

Warning

区分生成失败与下载失败。 本次实测默认 Python User-Agent 曾触发上游 403 / Cloudflare 1010。示例已设置 YM2API/1.0。URL 响应还需要单独下载,下载失败并不代表没有生成或没有计费。

4. 保存图片并检查

将下面保存为 save_images.py,运行 python save_images.py。它只处理本地响应文件,不会产生新生成请求。

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)} 字节")

检查点: 打开结果图片,核对主体是否来自参考图、画幅方向、文件实际尺寸以及输出张数。Grok 的 1:1 + 1k 实测为 1024×1024 JPEG ;其他比例看 Grok 比例表。

5. 一次只调整一个参数

每次修改 make_request.py 后重新生成 request.json,再提交一次。记录本次只改了什么。

顺序 调整 保持不变 检查结果
A quality 从 low 改为 medium 单参考图、1k、n=1 编辑效果、响应、账单
B resolution 改为 2k medium、n=1、同一提示词 1:1 实测变为 2048×2048 PNG
C aspect_ratio 改为 16:9 2k、medium、n=1 实测为 2816×1584 PNG
D 参考图从 1 张增加到 2/3 张 先保持 n=1 每张图是否贡献了所需内容
E 确有需要时将 n 改为 2 保持参考图和其他参数 是否返回两张;核对用量

Important

Grok 的稳定配置: aspect_ratio 控制画幅,resolution 控制 1k/2k 档位。不要依赖 size 精确指定像素;high、大写 2K、4k 均未通过。当前本站最多 3 张参考图,n 上限为 10。

多图排版请说明布局,例如“三张参考图排成一行,各出现一次”。本次三参考图实测保留了三个编号,但多出一个空白格,因此还需人工检查排版。

切换到 Adobe 分组时

#127【YYY】4k Image 2.0 (Med) 4K image2.5 flare / sunburst 建议先用 gpt-image-2、size="1536x864"、quality="medium"、n=1。它的尺寸参数与 Grok 不同;请更换对应分组的 Key,并照 Adobe 接口文档 的完整请求调整,不要直接沿用 Grok 参数。

6. 按失败阶段排错

现象 先检查 下一步
400 images 对象、Base64 前缀、prompt、n 类型 修正参数后再提交
401 / 403 Key、分组及响应正文 确认使用正确 Key;若是上游 1010,检查 User-Agent
422 quality、resolution、比例的枚举与大小写 恢复 low/medium、1k/2k、1:1 的基线
API 200,下载 403 出错发生在图片 URL 下载 下载时设置应用 User-Agent;不向图片域名发送本站 Key
超时 / 502 / 503 用量记录与通道状态 先确认是否已生成/扣费,待恢复后单图重测
200 但尺寸或编码不符 实际文件头、宽高、参数是否生效 查对应模型实测表;不要反复调无效参数

需要排查时保留:分组名称、模型、时间、HTTP 状态、错误正文、参数、实际尺寸 。分享日志前删除 Key、Authorization 头以及私有图片内容。

7. 继续阅读

Note

本教程中的请求结构基于既有实测;本次文档改版没有额外发起收费生图请求。代码示例进行了语法和本地样本检查。