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

# GPT-Image-2 Usage Guide

GPT-Image-2 is an AI image generation service provided by YYCode. It uses the independent image API at `gpt.yycode.net` to complete text-to-image, image-to-image, and asynchronous task queries.

---

## Preparation

### 1. Create an API Key

Go to the [YYCode Token Management page](https://yycode.net/console/token) and create or copy an API Key.

After creation, keep it safe. All subsequent requests need to carry this Key in the Header.

### 2. API Address

GPT-Image-2 uses an independent Base URL:

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

All image requests also carry the YYCode gateway address:

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

---

## One-click AI Agent Integration

When using AI coding tools that support Skills, such as Claude Code and Codex, send the following content directly to the AI:

```text
Please integrate the YYCode GPT-Image-2 image generation service into this project.

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

Text to image:
POST /api/images/generate

Image to image:
POST /api/images/edit

Query task:
GET /api/jobs/{jobId}

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

Use a JSON request body for text-to-image; use multipart/form-data for image-to-image and upload the source image through the image field.
After task submission returns jobId, query /api/jobs/{jobId} every 6 seconds.
After status=succeeded is returned, read images[].b64 and images[].mimeType, then save the base64 data as an image file.
```

The AI Agent will integrate client code according to the API, Headers, polling method, and image saving method above.

---

## API Details

### Text to Image

Submit a generation task:

```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": "A cute cat napping in the sunlight",
    "n": 1,
    "size": "1024x1024"
  }'
```

Successful response:

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

### Query Task Result

Replace `job_1782732290788_3` with the `jobId` returned when the task was submitted:

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

**Task processing:**

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

**Task completed:**

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

The final image data is `images[0].b64`, and the image format is `images[0].mimeType`. For frontend display, use `data:${mimeType};base64,${b64}`. For download, decode the base64 data into an image file.

---

### Image to Image

Image-to-image uses `multipart/form-data` to upload the source image, and submits the image file through the `image` field.

**Upload one source 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=Turn this image into a watercolor style' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'image=@input.png'
```

**Upload multiple source images:**

```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=Use these images as references to generate a unified cyberpunk poster' \
  -F 'n=1' \
  -F 'size=1536x1024' \
  -F 'image=@subject.png' \
  -F 'image=@style.png'
```

**Image-to-image notes:**

- `image` is the image file field. Repeat `image` when uploading multiple images
- `mask` is the image mask field, used for partial editing
- Do not manually set the `Content-Type` request header; let `curl` or the SDK automatically generate the multipart boundary
- Image-to-image tasks also return `jobId`, and results are queried through `GET /api/jobs/{jobId}`

---

## Parameter Description

| Parameter | Description |
|---|---|
| `model` | Fixed value: `gpt-image-2` |
| `prompt` | Prompt for image generation or image editing |
| `n` | Number of images to generate, from `1` to `10` |
| `size` | Output image size, in the format `<width>x<height>` |
| `output_format` | Output format; supports `png`, `jpeg`, `webp` |
| `quality` | Image quality; supports `auto`, `low`, `medium`, `high`, `standard`, `hd` |
| `background` | Background mode; supports `auto`, `opaque` |
| `image` | Source image file field for image-to-image; can be repeated |
| `mask` | Mask file field for image-to-image, used for partial editing |

### Supported size

`size` uses real pixel dimensions. Width and height must both be multiples of `16`, the longest side must not exceed `3840`, and total pixels must not exceed `3840x2160`.

| Size | Description |
|---|---|
| `1024x1024` | Square image |
| `1536x1024` | Landscape image |
| `1024x1536` | Portrait image |
| `1920x1080` | Landscape HD image |
| `1080x1920` | Portrait HD image |
| `3840x2160` | 4K landscape image |
| `2160x3840` | 4K portrait image |

---

## Python Example

```python
import base64
import time

import requests


# Replace with your 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",
}

# Step 1: Submit a text-to-image task
submit = requests.post(
    f"{base_url}/api/images/generate",
    headers=headers,
    json={
        "model": "gpt-image-2",
        "prompt": "A cute cat napping in the sunlight",
        "n": 1,
        "size": "1024x1024",
    },
    timeout=30,
)

submit.raise_for_status()
job_id = submit.json()["jobId"]
print(f"Task submitted: {job_id}")

# Step 2: Poll the task status every 6 seconds
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("Task processing...")
        time.sleep(6)
        continue

    if data.get("status") == "succeeded":
        # Step 3: Save the base64 image as a local file
        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"Image generation complete: {filename}")
        break

    raise RuntimeError(data.get("error", {}).get("message", "Task failed"))
```

---

## Billing Notes

- Image generation consumes the YYCode account quota associated with `x-demo-api-key`
- A submitted task returning `jobId` means the backend task has been created
- When the task status is `succeeded` and `images` is returned, this image generation is complete
- When the task status is `failed`, the response contains error information
- Account usage records are shown in the YYCode backend

---

## Image Return Notes

The YYCode image API returns a standardized `images` array. Each image contains `b64` and `mimeType` fields. Integrators can decode `b64` to save a file, or concatenate `data:${mimeType};base64,${b64}` for frontend display.