GPT Image 2 / 2.5 API — Generation and Image Editing

Use generations for text-to-image and multipart edits for reference images with GPT Image 2, Sunburst and Flare. Includes single-image, multi-image, Python and async examples.

GPT Image 2 / 2.5: tạo ảnh và chỉnh sửa ảnh

Hãy chọn endpoint trước khi viết request: text-to-image dùng /images/generations; image-to-image dùng /images/edits với các tệp ảnh đã tải lên. Việc nhắc đến “reference image 1” trong prompt không đính kèm ảnh.

Mô hình và endpoint

Model ID	Text-to-image	Image-to-image
`gpt-image-2`	`/images/generations`	`/images/edits` + các tệp ảnh
`gpt-image-2.5-sunburst`	`/images/generations`	`/images/edits` + các tệp ảnh
`gpt-image-2.5-flare`	`/images/generations`	`/images/edits` + các tệp ảnh

Đây là các model ID riêng biệt. Hãy thay đổi model một cách tường minh khi chuyển đổi mô hình; GPT Image 2.5 không phải là bí danh của GPT Image 2. Kiểm tra tình trạng khả dụng hiện tại và bảng giá tài khoản tại marketplace.

Thao tác	Phương thức và endpoint	Định dạng request
Text-to-image	`POST https://apimaster.ai/v1/images/generations`	JSON
Image-to-image / chỉnh sửa	`POST https://apimaster.ai/v1/images/edits`	`multipart/form-data` với các tệp ảnh thực tế
Chỉnh sửa ảnh bất đồng bộ	`POST https://apimaster.ai/v1/images/edits/async`	Các tệp multipart giống như chỉnh sửa; trả về một task ID
Text-to-image bất đồng bộ	`POST https://apimaster.ai/v1/images/generations/async`	JSON; trả về một task ID
Truy vấn một task	`GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID`	Xác thực Bearer

Để nhận phản hồi task từ việc chỉnh sửa ảnh, hãy dùng /images/edits/async. Tải lên cùng các tệp và trường như chỉnh sửa đồng bộ, sau đó truy vấn /tasks/{task_id}. Đừng chuyển một yêu cầu chỉnh sửa sang generations/async. Các endpoint task này tái sử dụng hợp đồng bất đồng bộ hiện có: một upstream bất đồng bộ có thể trả về task ngay lập tức, trong khi một upstream đồng bộ có thể hoàn tất việc chỉnh sửa trước khi gateway trả về task ID. Chúng không phải là lời hứa về việc thực thi nền tức thì. Đừng dùng Chat Completions cho các mô hình này.

Xác thực và thời gian chờ

Tạo một API key và gửi kèm Authorization: Bearer YOUR_API_KEY. Các yêu cầu tạo ảnh JSON dùng Content-Type: application/json. Khi tải tệp lên, để cURL hoặc thư viện HTTP của bạn tự tạo ranh giới multipart; đừng tự đặt thủ công header Content-Type.

Cho phép ít nhất 180 giây cho các yêu cầu cơ bản, 300 giây cho độ phân giải cao hơn, và 600 giây cho các yêu cầu chỉnh sửa phức tạp hoặc chất lượng cao. Việc client hết thời gian chờ không chứng minh rằng yêu cầu upstream đã dừng lại. Tránh gửi trùng lặp ngay lập tức.

Text-to-image: tạo ảnh bằng JSON

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Đối với Sunburst hoặc Flare, thay model ID bằng gpt-image-2.5-sunburst hoặc gpt-image-2.5-flare. Đừng thêm ảnh tham chiếu vào ví dụ này; hãy dùng các ví dụ chỉnh sửa bên dưới.

Image-to-image: tải lên một ảnh tham chiếu

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Thay reference.png bằng một ảnh cục bộ hiện có. @ báo cho cURL tải lên các byte của tệp; image=reference.png chỉ gửi một chuỗi tên tệp. Mẫu endpoint này cũng áp dụng cho gpt-image-2 và gpt-image-2.5-sunburst.

Image-to-image: tải lên nhiều ảnh tham chiếu

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Lặp lại cùng trường image[] cho mỗi tệp, theo thứ tự được mô tả trong prompt. n là số lượng ảnh đầu ra, không phải số lượng ảnh tham chiếu. Giới hạn ảnh tham chiếu phụ thuộc vào mô hình và route khả dụng; đừng giả định giới hạn chung là 16 ảnh. Hãy bắt đầu với một ảnh tham chiếu và n=1, sau đó thêm đầu vào khi cần.

Ví dụ chỉnh sửa bằng Python

Cài đặt requests. Ví dụ này tải lên một tệp thực và xử lý cả hai loại phản hồi ảnh URL và base64.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Với nhiều tệp, truyền một danh sách các mục ("image[]", (filename, file_object, mime_type)) lặp lại vào files. Giữ mỗi tệp mở cho đến khi yêu cầu hoàn tất.

Chỉnh sửa ảnh bất đồng bộ

Sử dụng endpoint này với GPT Image 2, Sunburst hoặc Flare khi ứng dụng của bạn sử dụng task ID. Quy tắc tải tệp lên, thứ tự ảnh tham chiếu, giới hạn tính năng và xác thực đều giống với chỉnh sửa đồng bộ.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Phần gửi yêu cầu trả về data[0].task_id. Poll bằng cùng model ID:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Một task được theo dõi đã hoàn tất có dạng như sau; mọi ảnh được tạo ra đều được bao gồm:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

Task thuộc về tài khoản đã gửi yêu cầu. Truy vấn nó bằng một API key hợp lệ cho tài khoản đó. Một yêu cầu gửi thất bại sẽ trả về lỗi chứ không phải một task dùng được; khi một task ID đã được trả về, hãy tiếp tục poll task đó thay vì gửi lại yêu cầu chỉnh sửa. Xem bảng trạng thái polling bên dưới.

Tích hợp URL hoặc base64 hiện có

Nếu đầu vào của bạn là một URL, hãy tải ảnh xuống trong ứng dụng của bạn và tải các byte của nó lên /images/edits. Nếu đó là một data URI base64, hãy giải mã payload thành một tệp hoặc bộ đệm byte rồi tải lên. Đừng gửi URL hoặc văn bản base64 như thể đó là một tệp tải lên.

Một số route của GPT Image 2 hỗ trợ phần mở rộng image_urls trên generations. Đó không phải là một hợp đồng chỉnh sửa ảnh khả chuyển và không được giả định là hoạt động với GPT Image 2.5. Các tích hợp mới nên dùng các ví dụ chỉnh sửa multipart ở trên. Một yêu cầu JSON chứa image_urls, image hoặc images không tương đương với việc tải tệp lên edits.

Tham số và giới hạn tính năng

Trường	Cách dùng
`model`	Bắt buộc; dùng một model ID chính xác từ bảng trên
`prompt`	Bắt buộc; mô tả kết quả và thứ tự ảnh tham chiếu
`image` / `image[]`	Các tệp thực tế được tải lên cho edits; dùng PNG hoặc JPEG cho các ví dụ cơ bản
`n`	Số lượng ảnh đầu ra; bắt đầu với `1`; mức tối đa phụ thuộc vào route
`size`	Tùy chọn; `1024x1024` là ví dụ cơ bản; các kích thước pixel hoặc tỷ lệ khung hình khác phụ thuộc vào route
`resolution`	Phần mở rộng tùy chọn theo route như `1k`, `2k`, `4k`; không phải mọi mô hình/route đều hỗ trợ mọi cấp độ
`quality`	Tùy chọn; các giá trị được chấp nhận và chi phí phụ thuộc vào route
`background`, `output_format`, `output_compression`	Tùy chọn; độ trong suốt và định dạng mã hóa đầu ra cần route hỗ trợ
`mask`	Chỉ GPT Image 2, khi một route edits khả dụng hỗ trợ mask được tải lên; không được hỗ trợ bởi trình xử lý multipart hiện tại của GPT Image 2.5

Với GPT Image 2, việc hỗ trợ mask phải được kiểm tra riêng biệt với việc chỉnh sửa ảnh tham chiếu thông thường. Một mask PNG tương thích phải khớp với kích thước đầu vào và bao gồm kênh alpha. Endpoint multipart hiện tại của GPT Image 2.5 từ chối các tệp mask được tải lên; đừng thêm mask vào các ví dụ Sunburst hoặc Flare ở trên. Đừng giả định một cách giải quyết bằng JSON với mask_url được hỗ trợ nếu chưa kiểm tra route đã chọn.

Chỉ gửi các trường tùy chọn mà bạn cần. Chúng có thể thay đổi các route đủ điều kiện và giá; việc thiết lập một giá trị mặc định một cách tường minh không phải lúc nào cũng tương đương với việc bỏ qua nó. Không có bảng kích thước pixel cố định hay danh sách tham số nâng cao nào áp dụng đồng nhất cho cả ba model ID. Giá thực tế và các tính năng được hỗ trợ tuân theo marketplace và phản hồi của yêu cầu.

Phản hồi đồng bộ

Một lần tạo hoặc chỉnh sửa thành công trả về các mục ảnh trong data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

Tùy thuộc vào route và định dạng đầu ra, một mục thay vào đó có thể chứa b64_json. Hãy giải mã nó thành các byte ảnh. Tải xuống các URL kết quả tạm thời ngay lập tức. Một phản hồi HTTP 200 hoặc số lượng ảnh một mình không chứng minh rằng các chi tiết tham chiếu đã được giữ nguyên; hãy kiểm tra kết quả so với đầu vào.

Task bất đồng bộ: gửi yêu cầu và polling

Đối với text-to-image, gửi JSON không có ảnh tham chiếu đến generations/async. Đối với chỉnh sửa ảnh, dùng ví dụ multipart edits/async ở trên. Cả hai đều dùng cùng endpoint truy vấn task:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

Phong bì (envelope) khi gửi yêu cầu thường báo submitted; một upstream có thể đã báo trạng thái hoàn tất. Lần poll đầu tiên có thể đã hoàn tất. Một task ID không đảm bảo phản hồi tức thì: nếu upstream đã chọn là đồng bộ, nền tảng sẽ đợi việc tạo ảnh hoàn tất trước khi trả về task. Hãy giữ một thời gian chờ gửi yêu cầu đủ dài.

Poll với cùng model ID đã dùng khi gửi yêu cầu:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Trạng thái task	Hành động
`pending`, `submitted`, `processing`, `in_progress`	Chờ; truy vấn lại sau 3–5 giây
`succeeded`, `success`, `completed`	Đọc mọi mục trong `data.result.images`; task được theo dõi dùng `url` dạng chuỗi, trong khi các phản hồi upstream kiểu cũ có thể dùng một mảng URL
`failed`, `error`, `cancelled`	Dừng polling và kiểm tra lỗi

Sử dụng một thời hạn polling tổng thể hữu hạn, ví dụ 10 phút. Nếu hết hạn, hãy giữ lại task ID để kiểm tra sau thay vì tự động tạo một task trả phí khác. Phản hồi truy vấn task và phản hồi ảnh đồng bộ có cấu trúc khác nhau.

Khắc phục sự cố ảnh tham chiếu

Xác minh đường dẫn yêu cầu thực tế là /v1/images/edits hoặc /v1/images/edits/async, không phải generations hoặc generations/async.
Xác minh multipart chứa các byte tệp dưới image hoặc image[] lặp lại, với ranh giới được tạo tự động. Văn bản prompt, tên tệp và số lượng tham chiếu không thay thế được các tệp.
Kiểm tra model ID chính xác. Một phần mở rộng của GPT Image 2 không tự động được Sunburst hoặc Flare hỗ trợ.
Nếu chi tiết task/log không hiển thị bản xem trước, đừng kết luận rằng không có ảnh nào được gửi: log có thể bỏ qua dữ liệu base64 và nội dung tệp đã tải lên. Ngược lại, số lượng tham chiếu được ghi log không chứng minh rằng một upstream đã sử dụng các ảnh đó.
Thử nghiệm với một ảnh tham chiếu đơn giản chứa chữ ký hoặc hình dạng đặc trưng, và yêu cầu thay đổi nền mà không mô tả các chi tiết đó. So sánh kết quả bằng mắt.
Khi liên hệ hỗ trợ, hãy giữ lại request ID (X-Oneapi-Request-Id), task ID nếu có, mô hình, endpoint, dấu thời gian, các trường yêu cầu đã được làm sạch và các ảnh tham chiếu. Không bao giờ chia sẻ API key của bạn.

Với phản hồi 400, hãy kiểm tra tính tương thích của endpoint và tham số; 401 cho biết xác thực thất bại; 429 cho biết giới hạn tốc độ/hạn mức. Với các trường hợp hết thời gian chờ hoặc upstream thất bại, hãy giữ lại request/task ID và kiểm tra task hoặc bản ghi sử dụng hiện có trước khi gửi lại.