# 从第一张图片开始

本教程使用 **#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，不含注释。

```python
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

```bash
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

```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`。它只处理本地响应文件，不会产生新生成请求。

```python
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 比例表](grok-imagine-image-api.html#3-比例与实际尺寸)。

## 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 接口文档](adobe-group127-api.html) 的完整请求调整，不要直接沿用 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. 继续阅读

- [#128【YYY】Grok Imagine 2K](grok-imagine-image-api.html)：参数、全部比例与 93 次请求的验证结果。
- [#127 Adobe 图片分组](adobe-group127-api.html)：10/6 张参考图边界、4K 实测与模型差异。
- [#75 超分 / #77 对接专用](gpt-image-2-api.html)：对应分组的尺寸与代理行为。

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