Hướng dẫn sử dụng GPT-Image-2

GPT-Image-2 là dịch vụ tạo ảnh AI do YYCode cung cấp, sử dụng giao diện ảnh độc lập gpt.yycode.net để hoàn thành text-to-image, image-to-image và truy vấn tác vụ bất đồng bộ.

Chuẩn bị

1. Tạo API Key

Vào trang quản lý token YYCode, tạo hoặc sao chép API Key.

Sau khi tạo xong, vui lòng lưu giữ cẩn thận; tất cả request tiếp theo đều cần mang Key này trong Header.

2. Địa chỉ giao diện

GPT-Image-2 sử dụng Base URL độc lập:

https://gpt.yycode.net

Tất cả request ảnh đồng thời mang địa chỉ trạm trung chuyển YYCode:

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

AI Agent kết nối một bước

Khi dùng các công cụ AI coding hỗ trợ Skills như Claude Code, Codex, hãy gửi trực tiếp nội dung sau cho AI:

Vui lòng tích hợp dịch vụ tạo ảnh YYCode GPT-Image-2 cho dự án này.

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

Text to Image:
POST /api/images/generate

Image to Image:
POST /api/images/edit

Truy vấn tác vụ:
GET /api/jobs/{jobId}

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

Text to Image dùng JSON request body; Image to Image dùng multipart/form-data và upload ảnh gốc bằng field image.
Sau khi submit tác vụ trả về jobId, truy vấn /api/jobs/{jobId} mỗi 6 giây.
Khi trả về status=succeeded, đọc images[].b64 và images[].mimeType, lưu base64 thành file ảnh.

AI Agent sẽ theo giao diện, Header, cách polling và cách lưu ảnh ở trên để hoàn tất tích hợp mã client.

Chi tiết API

Text to Image

Submit tác vụ tạo ảnh:

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": "Một chú mèo dễ thương đang ngủ gật dưới ánh nắng",
    "n": 1,
    "size": "1024x1024"
  }'

Phản hồi thành công:

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

Truy vấn kết quả tác vụ

Thay job_1782732290788_3 bằng jobId trả về khi submit tác vụ:

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

Đang xử lý tác vụ:

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

Tác vụ hoàn tất:

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

Dữ liệu ảnh cuối cùng là images[0].b64, định dạng ảnh là images[0].mimeType. Khi hiển thị ở frontend, dùng data:${mimeType};base64,${b64}; khi tải xuống, giải mã base64 thành file ảnh.

Image to Image

Image to Image dùng multipart/form-data upload ảnh gốc và submit file ảnh qua field image.

Upload một ảnh gốc:

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=Chuyển bức ảnh này sang phong cách màu nước' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F '[email protected]'

Upload nhiều ảnh gốc:

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=Tham khảo những ảnh này để tạo poster phong cách cyberpunk thống nhất' \
  -F 'n=1' \
  -F 'size=1536x1024' \
  -F '[email protected]' \
  -F '[email protected]'

Lưu ý về Image to Image:

• image là field file ảnh; khi upload nhiều ảnh, truyền lặp lại image
• mask là field file mask ảnh, dùng cho chỉnh sửa cục bộ
• Không tự đặt request header Content-Type; để curl hoặc SDK tự sinh multipart boundary
• Tác vụ Image to Image cũng trả về jobId và truy vấn kết quả qua GET /api/jobs/{jobId}

Tham số

Hỗ trợ size

size dùng kích thước pixel thật; chiều rộng và chiều cao đều là bội số của 16, cạnh dài nhất không vượt quá 3840, tổng pixel không vượt quá 3840x2160.

Ví dụ Python

import base64
import time

import requests


# Thay bằng YYCode API Key của bạn
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",
}

# Bước 1: submit tác vụ Text to Image
submit = requests.post(
    f"{base_url}/api/images/generate",
    headers=headers,
    json={
        "model": "gpt-image-2",
        "prompt": "Một chú mèo dễ thương đang ngủ gật dưới ánh nắng",
        "n": 1,
        "size": "1024x1024",
    },
    timeout=30,
)

submit.raise_for_status()
job_id = submit.json()["jobId"]
print(f"Tác vụ đã submit: {job_id}")

# Bước 2: polling trạng thái tác vụ mỗi 6 giây
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("Tác vụ đang xử lý...")
        time.sleep(6)
        continue

    if data.get("status") == "succeeded":
        # Bước 3: lưu ảnh base64 thành file local
        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"Tạo ảnh hoàn tất: {filename}")
        break

    raise RuntimeError(data.get("error", {}).get("message", "Tác vụ thất bại"))

Giải thích tính phí

• Tạo ảnh tiêu tốn hạn mức tài khoản YYCode thuộc x-demo-api-key
• Submit tác vụ trả về jobId nghĩa là tác vụ backend đã được tạo
• Khi trạng thái tác vụ là succeeded và trả về images, lần tạo ảnh này hoàn tất
• Khi trạng thái tác vụ là failed, phản hồi sẽ trả về thông tin lỗi
• Bản ghi sử dụng tài khoản được hiển thị trong backend YYCode

Giải thích dữ liệu ảnh trả về

Giao diện ảnh YYCode trả về mảng images đã chuẩn hóa. Mỗi ảnh chứa trường b64 và mimeType; bên tích hợp dùng b64 để giải mã lưu file, hoặc ghép data:${mimeType};base64,${b64} để hiển thị ở frontend.