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 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:

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:

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:

{
  "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:

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

Task processing:

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

Task completed:

{
  "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:

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

Upload multiple source images:

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

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

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.

Python Example

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.