canonical_url: https://yycode.net/docs/zh-TW/gpt-image-quickstart
lang: zh-TW
updated_at: 2026-07-04T13:33:48.616Z
source_html: https://yycode.net/docs/zh-TW/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}` 在前端展示。