canonical_url: https://yycode.net/docs/zh-CN/gpt-image-quickstart
lang: zh-CN
updated_at: 2026-07-04T13:33:48.616Z
source_html: https://yycode.net/docs/zh-CN/gpt-image-quickstart

# GPT-Image-2 使用指南

GPT-Image-2 是 YYCode 提供的 AI 图片生成服务，使用 `gpt.yycode.net` 独立图片接口完成文生图、图生图和异步任务查询。

---

## 准备工作

### 1. 创建 API Key

前往 [YYCode 令牌管理页面](https://yycode.net/console/token)，创建或复制 API Key。

创建完成后请妥善保存，后续所有请求都需要在 Header 中携带此 Key。

### 2. 接口地址

GPT-Image-2 使用独立 Base URL：

```
https://gpt.yycode.net
```

所有图片请求同时携带 YYCode 中转站地址：

```
x-demo-base-url: https://yycode.net
```

---

## AI Agent 一键接入

使用 Claude Code、Codex 等支持 Skills 的 AI 编码工具时，直接将以下内容发送给 AI：

```text
请为这个项目接入 YYCode GPT-Image-2 图片生成服务。

Base URL:
https://gpt.yycode.net

文生图:
POST /api/images/generate

图生图:
POST /api/images/edit

查询任务:
GET /api/jobs/{jobId}

请求 Header:
x-demo-base-url: https://yycode.net
x-demo-api-key: YOUR_API_KEY
x-demo-async: 1

文生图使用 JSON 请求体；图生图使用 multipart/form-data，并用 image 字段上传原图。
提交任务返回 jobId 后，每 6 秒查询 /api/jobs/{jobId}。
返回 status=succeeded 后读取 images[].b64 和 images[].mimeType，将 base64 保存为图片文件。
```

AI Agent 会按照上述接口、Header、轮询方式和图片保存方式完成客户端代码接入。

---

## API 详细说明

### 文生图（Text to Image）

提交生成任务：

```bash
curl 'https://gpt.yycode.net/api/images/generate' \
  -H 'Content-Type: application/json' \
  -H 'x-demo-base-url: https://yycode.net' \
  -H 'x-demo-api-key: YOUR_API_KEY' \
  -H 'x-demo-async: 1' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只可爱的猫咪在阳光下打盹",
    "n": 1,
    "size": "1024x1024"
  }'
```

成功响应：

```json
{
  "ok": true,
  "pending": true,
  "jobId": "job_1782732290788_3",
  "meta": {
    "requestId": "req_1782732290788_1"
  }
}
```

### 查询任务结果

将 `job_1782732290788_3` 替换为提交任务时返回的 `jobId`：

```bash
curl 'https://gpt.yycode.net/api/jobs/job_1782732290788_3'
```

**任务处理中：**

```json
{
  "ok": true,
  "pending": true,
  "jobId": "job_1782732290788_3",
  "status": "running",
  "meta": {
    "requestId": "req_1782732290788_1"
  }
}
```

**任务完成：**

```json
{
  "ok": true,
  "images": [
    {
      "b64": "iVBORw0KGgo...",
      "filename": null,
      "mimeType": "image/png"
    }
  ],
  "usage": null,
  "raw": {},
  "meta": {
    "requestId": "req_1782732290788_1"
  },
  "jobId": "job_1782732290788_3",
  "status": "succeeded"
}
```

最终图片数据为 `images[0].b64`，图片格式为 `images[0].mimeType`。前端展示时使用 `data:${mimeType};base64,${b64}`，下载时将 base64 解码为图片文件。

---

### 图生图（Image to Image）

图生图使用 `multipart/form-data` 上传原图，并通过 `image` 字段提交图片文件。

**上传一张原图：**

```bash
curl 'https://gpt.yycode.net/api/images/edit' \
  -H 'x-demo-base-url: https://yycode.net' \
  -H 'x-demo-api-key: YOUR_API_KEY' \
  -H 'x-demo-async: 1' \
  -F 'model=gpt-image-2' \
  -F 'prompt=把这张图改成水彩风格' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'image=@input.png'
```

**上传多张原图：**

```bash
curl 'https://gpt.yycode.net/api/images/edit' \
  -H 'x-demo-base-url: https://yycode.net' \
  -H 'x-demo-api-key: YOUR_API_KEY' \
  -H 'x-demo-async: 1' \
  -F 'model=gpt-image-2' \
  -F 'prompt=参考这些图片生成统一的赛博朋克风格海报' \
  -F 'n=1' \
  -F 'size=1536x1024' \
  -F 'image=@subject.png' \
  -F 'image=@style.png'
```

**图生图注意事项：**

- `image` 为图片文件字段，上传多张图片时重复传入 `image`
- `mask` 为图片蒙版字段，用于局部编辑
- 请求头不手动设置 `Content-Type`，由 `curl` 或 SDK 自动生成 multipart boundary
- 图生图任务同样返回 `jobId`，并通过 `GET /api/jobs/{jobId}` 查询结果

---

## 参数说明

| 参数 | 说明 |
|---|---|
| `model` | 固定填写 `gpt-image-2` |
| `prompt` | 图片生成或图片编辑提示词 |
| `n` | 生成图片数量，范围 `1` 到 `10` |
| `size` | 输出图片尺寸，格式为 `<width>x<height>` |
| `output_format` | 输出格式，支持 `png`、`jpeg`、`webp` |
| `quality` | 图片质量，支持 `auto`、`low`、`medium`、`high`、`standard`、`hd` |
| `background` | 背景模式，支持 `auto`、`opaque` |
| `image` | 图生图原图文件字段，支持重复传入 |
| `mask` | 图生图蒙版文件字段，用于局部编辑 |

### size 支持

`size` 使用真实像素尺寸，宽高均为 `16` 的倍数，最长边不超过 `3840`，总像素不超过 `3840x2160`。

| 尺寸 | 说明 |
|---|---|
| `1024x1024` | 正方形图片 |
| `1536x1024` | 横向图片 |
| `1024x1536` | 竖向图片 |
| `1920x1080` | 横屏高清图片 |
| `1080x1920` | 竖屏高清图片 |
| `3840x2160` | 4K 横屏图片 |
| `2160x3840` | 4K 竖屏图片 |

---

## Python 示例

```python
import base64
import time

import requests


# 替换为你的 YYCode API Key
base_url = "https://gpt.yycode.net"
api_key = "YOUR_API_KEY"

headers = {
    "Content-Type": "application/json",
    "x-demo-base-url": "https://yycode.net",
    "x-demo-api-key": api_key,
    "x-demo-async": "1",
}

# 步骤一：提交文生图任务
submit = requests.post(
    f"{base_url}/api/images/generate",
    headers=headers,
    json={
        "model": "gpt-image-2",
        "prompt": "一只可爱的猫咪在阳光下打盹",
        "n": 1,
        "size": "1024x1024",
    },
    timeout=30,
)

submit.raise_for_status()
job_id = submit.json()["jobId"]
print(f"任务已提交: {job_id}")

# 步骤二：每 6 秒轮询查询任务状态
while True:
    result = requests.get(
        f"{base_url}/api/jobs/{job_id}",
        timeout=30,
    )
    result.raise_for_status()

    data = result.json()

    if data.get("pending"):
        print("任务处理中...")
        time.sleep(6)
        continue

    if data.get("status") == "succeeded":
        # 步骤三：将 base64 图片保存为本地文件
        image = data["images"][0]
        mime_type = image.get("mimeType") or "image/png"
        suffix = mime_type.split("/")[-1].replace("jpeg", "jpg")
        filename = f"{job_id}.{suffix}"

        with open(filename, "wb") as file:
            file.write(base64.b64decode(image["b64"]))

        print(f"图片生成完成: {filename}")
        break

    raise RuntimeError(data.get("error", {}).get("message", "任务失败"))
```

---

## 计费说明

- 图片生成消耗 `x-demo-api-key` 所属 YYCode 账户额度
- 提交任务返回 `jobId` 表示后台任务已创建
- 任务状态为 `succeeded` 且返回 `images` 后，本次图片生成完成
- 任务状态为 `failed` 时，响应中返回错误信息
- 账户用量记录在 YYCode 后台展示

---

## 图片返回说明

YYCode 图片接口返回标准化 `images` 数组。每张图片包含 `b64` 和 `mimeType` 字段，接入方使用 `b64` 解码保存文件，或拼接 `data:${mimeType};base64,${b64}` 在前端展示。