Claude Opus 5.5 đã có trên SeedRouter
LogoSeedRouter
Tất cả bài viết

GPT Image 2.5 API với Python: ví dụ chạy được

Gọi GPT Image 2.5 API từ Python và JavaScript, truy vấn tác vụ để lấy URL ảnh, chỉnh sửa bằng ảnh tham chiếu và khắc phục lỗi ID mô hình và tham số.

Đọc dạng Markdown

Để gọi GPT Image 2.5 API, hãy gửi POST tới https://api.seedrouter.ai/v1/images/generations với một ID mô hình như gpt-image-2.5-flare và một prompt, giữ lại id của tác vụ trong phản hồi, rồi truy vấn GET /v1/tasks/{id} cho tới khi trạng thái là completed. Tác vụ hoàn tất chứa URL tới các ảnh của bạn. Cùng một endpoint xử lý tạo ảnh từ văn bản, chỉnh sửa theo ảnh tham chiếu và chỉnh sửa có mặt nạ.

Hướng dẫn này là một quy trình hoàn chỉnh, chạy được bằng Python, kèm bản tương đương bằng JavaScript, tiếp theo là các lỗi hay gặp nhất và ý nghĩa của từng lỗi.

Cần chuẩn bị gì trước yêu cầu đầu tiên?

Hai thứ: một khóa API và một ID mô hình.

Tạo khóa trên trang khóa API và giữ nó trong biến môi trường trên máy chủ của bạn, đừng bao giờ đặt trong code chạy trên trình duyệt:

export SEEDROUTER_API_KEY="your-key"

Sau đó chọn một trong bốn ID mô hình GPT Image 2.5. Hãy sao chép chính xác; không có ID gpt-image-2.5 trần.

ID mô hìnhMô hìnhCách tính phí
gpt-image-2.5-flareFlareGiá cố định mỗi ảnh
gpt-image-2.5-sunburstSunburstGiá cố định mỗi ảnh
gpt-image-2.5-flare-officialFlareMức dùng token
gpt-image-2.5-sunburst-officialSunburstMức dùng token

Nếu bạn chưa chắc nên bắt đầu với mô hình nào, hãy dùng Flare; Flare vs Sunburst giải thích khi nào Sunburst đáng dùng.

Tạo ảnh bằng Python thế nào?

Lệnh gửi trả về ngay lập tức. Phản hồi là một tham chiếu tác vụ, không phải ảnh.

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

Hãy lưu task_id trước khi làm bất cứ việc gì khác. Đó là cách duy nhất để nắm lấy công việc bạn vừa trả tiền, và là cách để khôi phục nếu tiến trình của bạn khởi động lại trong lúc ảnh đang được dựng.

Lấy ảnh về bằng cách nào?

Truy vấn tác vụ vài giây một lần cho tới khi nó hoàn tất. Vòng lặp này chờ tối đa mười phút; chạm tới hạn chót đó chỉ dừng vòng lặp của bạn, không dừ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}.")

Hãy tải về các URL bạn muốn giữ và tự lưu trữ chúng. URL kết quả là điểm bàn giao, không phải nơi lưu trữ lâu dài.

Cùng lệnh gọi đó trong JavaScript trông thế nào?

Yêu cầu giống hệt; chỉ HTTP client thay đổi. Hãy chạy nó trên máy chủ để khóa không bao giờ đến được trình duyệt.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

Truy vấn GET https://api.seedrouter.ai/v1/tasks/${taskId} với cùng header, đúng như trong vòng lặp Python.

Chỉnh sửa một ảnh có sẵn thế nào?

Thêm ảnh tham chiếu vào cùng yêu cầu đó. Không có endpoint chỉnh sửa riêng và không có trường chế độ: gửi images biến yêu cầu thành chỉnh sửa, và thêm mask sẽ giới hạn thay đổi trong một vùng.

{
  "model": "gpt-image-2.5-sunburst",
  "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"}
}

Đầu vào phải là URL HTTPS công khai. Bạn có thể gửi tối đa 16 ảnh tham chiếu dạng PNG, JPEG hoặc WebP, mỗi ảnh dưới 50 MB. Mặt nạ là một ảnh PNG dưới 4 MB, cùng kích thước với ảnh tham chiếu đầu tiên, và vùng trong suốt của nó đánh dấu phần cần đổi. Chuỗi Base64, URL data: và tải tệp lên trực tiếp đều bị từ chối, nên hãy tải tệp lên kho lưu trữ của riêng bạn trước rồi gửi URL.

Vì sao API báo mô hình không khả dụng?

Mã lỗi 20002 với HTTP 400 (“The requested model is not available.”) nghĩa là giá trị model không phải một ID mà API phục vụ. Nguyên nhân thường gặp là sai một chút: gpt-image-2.5 thiếu phiên bản, gpt-image-2-5-flare dùng dấu gạch ngang thay cho dấu chấm, hoặc gõ nhầm sunburst. Hãy sao chép một ID từ bảng ở trên.

Lỗi tham số được báo trước khi mô hình được kiểm tra. Nếu yêu cầu còn có một trường không hợp lệ, bạn nhận 20001 với thông báo nêu tên trường đó, ví dụ quality. Hãy sửa lỗi đó trước; lỗi mô hình sẽ xuất hiện ở lần thử tiếp theo nếu ID vẫn sai.

Mã lỗiHTTPCách xử lý
20001400Sửa trường được nêu trong thông báo
20002400Dùng chính xác một trong bốn ID mô hình
10001401Kiểm tra header Authorization

Một tác vụ cũng có thể thất bại sau khi đã được tiếp nhận. Truy vấn đó vẫn trả về HTTP 200, với status: "failed" và một đối tượng error như mã 60001 (chính sách nội dung) hoặc 60002 (tạo thất bại). Tác vụ thất bại không bị tính phí. Danh mục lỗi liệt kê mọi mã, bao gồm lỗi số dư và lỗi giới hạn tần suất, kèm bước xử lý tiếp theo cho từng mã.

Câu hỏi thường gặp

Có lệnh gọi Python SDK chính thức nào trả về ảnh trực tiếp không?

Không có trên API này. Việc giao ảnh là bất đồng bộ: bạn luôn gửi, giữ ID tác vụ và truy vấn. stream và partial_images không được hỗ trợ.

Có thể yêu cầu nhiều ảnh cùng lúc không?

Có. Đặt n từ 1 đến 10. Tác vụ hoàn tất liệt kê một URL cho mỗi ảnh được giao, và bạn bị tính phí theo số ảnh được giao.

Làm sao lấy ảnh PNG trong suốt?

Đặt background thành transparent và output_format thành png. JPEG không có kênh alpha, nên tổ hợp đó bị từ chối trước khi chạy.

Xây dựng tích hợp xoay quanh ID tác vụ

Lưu ID tác vụ ngay khi nhận được, truy vấn có hạn chót, và coi hết thời gian chờ khi truy vấn là "vẫn đang chạy" chứ không phải "thất bại". Mọi thứ khác, gồm mọi trường và giới hạn, nằm trong tài liệu tham khảo GPT Image 2.5 API, và bạn có thể thử một yêu cầu mà không cần code trong Playground.

Tất cả bài viết

Hướng dẫn liên quan