GPT Image 2.5
Tạo và chỉnh sửa ảnh với GPT Image 2.5 Flare hoặc Sunburst qua một endpoint ảnh bất đồng bộ duy nhất, với sáu mức chất lượng tới max.
GPT Image 2.5 nhận một prompt văn bản và tùy chọn thêm ảnh tham chiếu. Gửi một lần, giữ lại ID tác vụ được trả về, rồi truy vấn tác vụ đó để lấy ảnh đã hoàn thành. Mô hình được cung cấp dưới dạng hai mô hình dùng cùng tham số: Flare cho công việc hằng ngày và Sunburst khi độ chính xác của chỉnh sửa là quan trọng nhất.
ID mô hình
| ID mô hình | Phiên bản | Kênh |
|---|---|---|
gpt-image-2.5-flare | Flare: lựa chọn mặc định cho hầu hết ứng dụng | Standard |
gpt-image-2.5-sunburst | Sunburst: mạnh nhất, kiểm soát chặt chẽ hơn qua các lần chỉnh sửa, chậm hơn | Standard |
gpt-image-2.5-flare-official | Flare | Official |
gpt-image-2.5-sunburst-official | Sunburst | Official |
Cả bốn ID nhận cùng tham số. Các kênh chỉ khác nhau ở cách tính phí; xem giá hiện tại trên trang mô hình.
Ví dụ nhanh
curl https://api.seedrouter.ai/v1/images/generations \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-flare",
"prompt": "An amber glass bottle on a cream background, studio lighting",
"size": "1024x1024",
"quality": "low"
}'Endpoint
POST https://api.seedrouter.ai/v1/images/generations| Header | Giá trị |
|---|---|
| Authorization | Bearer YOUR_API_KEY |
| Content-Type | application/json |
Cùng một endpoint xử lý việc tạo ảnh, chỉnh sửa theo ảnh tham chiếu và chỉnh sửa theo mặt nạ. Phản hồi chứa ID tác vụ chứ không phải ảnh đã hoàn thành. Hãy giữ khóa API trong mã phía máy chủ.
Tham số
| Tên | Kiểu | Bắt buộc | Mặc định | Ghi chú |
|---|---|---|---|---|
model | string | Có | — | Một trong bốn ID mô hình ở trên. |
prompt | string | Có | — | Không được rỗng; tối đa 32.000 ký tự. |
images | object[] | Không | — | Từ 1 đến 16 đối tượng dạng {"image_url":"https://..."}; truyền images sẽ chuyển sang chế độ chỉnh sửa. |
mask | object | Không | — | {"image_url":"https://..."}; cần có images. |
size | string | Không | auto | auto hoặc WIDTHxHEIGHT, theo các quy tắc bên dưới. |
quality | enum | Không | auto | auto, low, medium, high, xhigh, max. |
background | enum | Không | auto | auto, opaque, transparent. |
output_format | enum | Không | png | png, jpeg. |
output_compression | integer | Không | 100 với JPEG | Từ 0 đến 100; chỉ gửi kèm jpeg. Giá trị 0 là hợp lệ. |
n | integer | Không | 1 | Từ 1 đến 10 ảnh. |
moderation | enum | Không | auto | auto, low. |
user | string | Không | — | Định danh tùy chọn cho người dùng cuối của ứng dụng bạn. Tránh đưa thông tin cá nhân. |
Quy tắc kích thước
Các lựa chọn phổ biến là 1024x1024, 1536x1024 và 1024x1536. Kích thước tùy chỉnh phải thỏa mãn mọi quy tắc:
- Chiều rộng và chiều cao là bội số của 16.
- Không cạnh nào vượt quá 3840 pixel.
- Tỉ lệ khung hình nằm trong khoảng từ 1:3 đến 3:1.
- Tổng diện tích nằm trong khoảng từ 655.360 đến 8.294.400 pixel, bao gồm cả hai đầu.
auto để mô hình tự quyết định kích thước đầu ra. Đừng gửi tỉ lệ khung hình như 16:9 vào size.
Playground cung cấp các điều khiển Auto, Tỉ lệ và Tùy chỉnh. Chế độ Tỉ lệ kết hợp một tỉ lệ khung hình với mức ngân sách pixel 1K, 2K hoặc 4K, rồi chỉ gửi size tính được. Đây là các thiết lập sẵn của giao diện, không phải tham số API riêng: đừng gửi resolution hay aspect_ratio. Ví dụ, 16:9 + 4K gửi size: "3840x2160"; 9:16 + 4K gửi "2160x3840"; 1:1 + 2K gửi "2048x2048". Việc làm tròn và giới hạn cạnh có thể làm giảm số pixel của mức đã chọn. Kích thước chính xác được hiển thị trước khi gửi.
OpenAI mô tả các độ phân giải trên 2560×1440 là mang tính thử nghiệm. Chúng vẫn được chấp nhận trong các giới hạn nêu trên; độ phân giải cao hơn không bảo đảm chi tiết tốt hơn.
Mức chất lượng
xhigh và max là các mức mới trong GPT Image 2.5; GPT Image 2 chỉ đến high. Mức càng cao thì thời gian dựng ảnh càng lâu và, với các ID tính phí theo token, tiêu tốn nhiều token đầu ra hơn. Đo ở 1024x1024, một lần dựng ảnh báo về 196, 439, 1.756, 3.122 và 7.024 token đầu ra lần lượt cho low, medium, high, xhigh và max. Đây là các mẫu quan sát được, không phải cam kết: mức sử dụng còn phụ thuộc vào kích thước và nội dung.
Hãy dùng low cho bản nháp và so sánh kết quả trước khi chọn mức cao hơn. auto để mô hình tự chọn; nó không bảo đảm một mức hay một mức chi phí cụ thể nào.
Nền trong suốt
GPT Image 2.5 hỗ trợ nền trong suốt. Để có nền trong suốt, hãy đặt background: "transparent" và dùng PNG. JPEG không hỗ trợ độ trong suốt. Nén chỉ áp dụng cho JPEG.
user có sẵn cho các tích hợp API nhưng không hiển thị và cũng không được điền tự động trong Playground.
Các thiết lập vô hướng tùy chọn (n, size, quality, background, output_format, output_compression, moderation) chấp nhận null như cách bỏ qua. Các trường không xác định sẽ bị từ chối. input_fidelity không phải là tham số của GPT Image 2.5. style và response_format thuộc về các mô hình ảnh khác và không được chấp nhận ở đây.
Các chế độ
Không có tham số chế độ riêng hay endpoint chỉnh sửa riêng để bạn phải chọn.
| Thao tác | Tham số |
|---|---|
| Văn bản thành ảnh | prompt |
| Chỉnh sửa theo ảnh tham chiếu | prompt + images |
| Chỉnh sửa theo mặt nạ | prompt + images + mask |
Chỉnh sửa ảnh tham chiếu
curl https://api.seedrouter.ai/v1/images/generations \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-flare",
"prompt": "Make the bottle blue. Preserve the composition and lighting.",
"images": [{"image_url": "https://example.com/reference.png"}],
"mask": {"image_url": "https://example.com/mask.png"},
"output_format": "jpeg",
"output_compression": 90
}'Hãy thay cả hai URL ví dụ bằng ảnh của bạn mà hệ thống truy cập được. Bỏ mask nếu muốn chỉnh sửa theo ảnh tham chiếu mà không giới hạn vùng.
Đầu vào media
API này chỉ nhận tham chiếu bằng URL. Không chấp nhận ID của OpenAI Files, data URL base64 và tải lên dạng multipart. Playground tải các tệp đã chọn lên kho lưu trữ trước, rồi mới gửi URL của chúng.
Ảnh tham chiếu phải là URL HTTP(S) công khai trỏ tới tệp PNG, JPEG hoặc WebP nhỏ hơn 50 MB mỗi tệp. Mặt nạ phải là tệp PNG nhỏ hơn 4 MB, cùng kích thước với ảnh tham chiếu đầu tiên; vùng trong suốt của nó đánh dấu phần cần chỉnh sửa. Mặt nạ chỉ định hướng cho mô hình và không bảo đảm ranh giới chính xác tới từng pixel. Khi có nhiều ảnh tham chiếu, mặt nạ áp dụng cho ảnh đầu tiên. Media theo URL được kiểm tra trong lúc xử lý; media không hợp lệ hoặc không truy cập được có thể khiến tác vụ thất bại.
Playground tải các tệp đã chọn lên và gửi URL của chúng. Yêu cầu API dùng đối tượng URL dạng JSON: đừng gửi byte tệp, base64, URL data:, URL blob: hay dữ liệu biểu mẫu multipart.
Các yếu tố chi phí
Hãy xem phần giá của mô hình để biết biểu phí hiện tại. Các ID Standard tính một mức giá cố định cho mỗi ảnh được giao, bất kể chất lượng, kích thước hay prompt. Với các ID Official, chi phí cuối cùng phụ thuộc vào lượng đầu vào và đầu ra: chất lượng, kích thước đầu ra, ảnh tham chiếu, độ dài prompt và số lượng ảnh đều có thể ảnh hưởng.
Ước tính của Playground dựa trên mẫu đo thực tế và biểu phí hiện tại; đây không phải báo giá bảo đảm. Hãy xem chi phí cuối cùng trong lịch sử sử dụng của tài khoản. Tác vụ thất bại không bị tính phí.
Lược đồ đầu ra
Khi gửi, API trả về một tham chiếu tác vụ:
{
"id": "task_...",
"model": "gpt-image-2.5-flare",
"status": "processing",
"created_at": 1789970508
}Truy vấn tác vụ
curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
-H "Authorization: Bearer $SEEDROUTER_API_KEY"Hãy truy vấn với nhịp vừa phải, chẳng hạn ba giây một lần, cho đến khi status là completed hoặc failed. Hết thời gian mạng trong lúc truy vấn không có nghĩa là việc tạo ảnh đã thất bại: hãy giữ ID tác vụ và tiếp tục kiểm tra. Đừng tạo tác vụ khác chỉ để xem tiến độ.
Ví dụ truy vấn đầy đủ
Hãy chạy đoạn này sau ví dụ gửi bằng Python ở trên. Nó dùng task_id được trả về và chờ tối đa mười phút. Chạm tới mốc thời gian cục bộ này chỉ dừng việc truy vấn; hãy giữ ID và tiếp tục truy vấn đúng tác vụ đó.
import time
print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
result = requests.get(
f"https://api.seedrouter.ai/v1/tasks/{task_id}",
headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
timeout=30,
)
result.raise_for_status()
task = result.json()
if task["status"] == "completed":
for image in task["output"]["data"]:
print(image["url"])
break
if task["status"] == "failed":
raise RuntimeError(task["error"]["message"])
time.sleep(3)
else:
raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")Tác vụ đã hoàn tất
Tác vụ đã hoàn tất trả về URL ảnh được lưu trữ cùng thông tin mức sử dụng:
{
"id": "task_...",
"model": "gpt-image-2.5-flare",
"status": "completed",
"created_at": 1789970508,
"finished_at": 1789970538,
"output": {
"created": 1789970532,
"data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
"usage": {
"input_tokens": 29,
"output_tokens": 196,
"total_tokens": 225
}
}
}| Trường | Ý nghĩa |
|---|---|
id | Hãy giữ ID này cho các lần truy vấn sau. |
status | processing, completed hoặc failed. |
created_at, finished_at | Dấu thời gian Unix tính bằng giây; trong lúc xử lý, thời điểm hoàn tất để trống hoặc bằng 0. |
output.data[].url | URL của ảnh đã tạo, có sẵn khi tác vụ hoàn tất. |
output.size | Kích thước đầu ra thực tế, khi được báo cáo. |
output.quality | Mức chất lượng thực tế, khi được báo cáo. |
output.background | Nền thực tế, khi được báo cáo. |
output.output_format | Định dạng ảnh thực tế, khi được báo cáo. |
output.usage | Mức sử dụng token được báo cáo, khi có. Các đối tượng chi tiết có thể chứa số token văn bản và ảnh. |
error | Lỗi có cấu trúc của một tác vụ thất bại. |
API này trả kết quả theo cơ chế tác vụ bất đồng bộ. Đây không phải bản thay thế cho SDK Images đồng bộ; stream và partial_images không được hỗ trợ.
Lỗi
Những yêu cầu bị từ chối trước khi tác vụ được tạo sẽ trả về lỗi HTTP kèm đối tượng error. Tác vụ thất bại sau khi đã được tiếp nhận sẽ trả về HTTP 200 khi truy vấn, kèm status: "failed" và một đối tượng error.
Hãy xem danh mục lỗi dùng chung để biết mã lỗi, mã trạng thái HTTP và hướng dẫn thử lại. Mọi API mô hình đều dùng chung một cấu trúc lỗi.
{
"id": "task_...",
"status": "failed",
"error": {
"code": 60002,
"message": "Generation could not be completed. Please try again."
}
}Nếu chính lần gửi bị hết thời gian chờ, hãy kiểm tra lịch sử tác vụ trước khi gửi lại: yêu cầu đầu tiên có thể đã được tiếp nhận.
Mẹo
- Hãy mô tả chất liệu, bố cục và ánh sáng trong prompt.
- Khi chỉnh sửa, hãy nêu rõ cả phần cần thay đổi lẫn phần phải giữ nguyên.
- Dùng mặt nạ khi chỉ một vùng được chọn cần thay đổi.
- Hãy lưu ảnh trả về vào kho lưu trữ của riêng bạn nếu cần bản sao lâu dài.