GPT-Image-2 使用指南

GPT-Image-2 是 YYCode 提供的 AI 圖片生成服務，使用 gpt.yycode.net 獨立圖片介面完成文生圖、圖生圖和異步任務查詢。

準備工作

1. 建立 API Key

前往 YYCode 權杖管理頁面，建立或複製 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：

請為這個專案接入 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）

提交生成任務：

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"
  }'

成功回應：

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

查詢任務結果

將 job_1782732290788_3 替換為提交任務時回傳的 jobId：

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

任務處理中：

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

任務完成：

{
  "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 欄位提交圖片檔案。

上傳一張原圖：

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 '[email protected]'

上傳多張原圖：

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 '[email protected]' \
  -F '[email protected]'

圖生圖注意事項：

• image 為圖片檔案欄位，上傳多張圖片時重複傳入 image
• mask 為圖片蒙版欄位，用於局部編輯
• 請求頭不手動設置 Content-Type，由 curl 或 SDK 自動生成 multipart boundary
• 圖生圖任務同樣回傳 jobId，並通過 GET /api/jobs/{jobId} 查詢結果

參數說明

size 支援

size 使用真實像素尺寸，寬高均為 16 的倍數，最長邊不超過 3840，總像素不超過 3840x2160。

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} 在前端展示。