GPT Image 2 API với Python: ví dụ hoàn chỉnh

Để dùng GPT Image 2 API từ Python, hãy gửi POST yêu cầu của bạn tới https://api.seedrouter.ai/v1/images/generations bằng thư viện requests, giữ lại id của tác vụ được trả về, truy vấn /v1/tasks/{id} cho tới khi tác vụ ở trạng thái completed, rồi tải các URL ảnh mà nó liệt kê. Script dưới đây làm cả bốn bước trong khoảng 40 dòng và lưu ảnh xuống ổ đĩa.

Script chạy được ngay khi đã đặt SEEDROUTER_API_KEY. Nếu bạn chưa có khóa, hãy lấy khóa trước.

Một script GPT Image 2 hoàn chỉnh trông như thế nào?

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    response = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
    return response.json()["id"]


def wait(task_id, limit_seconds=600):
    deadline = time.monotonic() + limit_seconds
    while time.monotonic() < deadline:
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] == "completed":
            return [image["url"] for image in task["output"]["data"]]
        if task["status"] == "failed":
            raise RuntimeError(f"{task['error']['code']}: {task['error']['message']}")
        time.sleep(3)
    raise TimeoutError(f"Still running. Resume polling task {task_id}.")


def download(urls, prefix):
    paths = []
    for index, url in enumerate(urls):
        path = f"{prefix}-{index}.png"
        with open(path, "wb") as file:
            file.write(requests.get(url, timeout=60).content)
        paths.append(path)
    return paths


task_id = submit({
    "model": "gpt-image-2",
    "prompt": "A matte ceramic vase on a sunlit table, soft shadows",
    "size": "1024x1024",
    "quality": "low",
    "n": 2,
})
print("task", task_id)
print(download(wait(task_id), "vase"))

Chạy bằng python example.py. Script in ra ID tác vụ trước, sau đó là đường dẫn của hai tệp PNG, vase-0.png và vase-1.png.

Mỗi hàm làm gì?

submit gửi yêu cầu và trả về ID tác vụ. Phản hồi lỗi luôn có một đối tượng error gồm code dạng số và message, nên ngoại lệ cho bạn biết cần sửa gì. Chẳng hạn, lỗi 400 với mã 20001 và thông báo “Check the size parameter against the API documentation.” nghĩa là kích thước đã vi phạm một trong các quy tắc trong hướng dẫn tham số.

wait truy vấn ba giây một lần cho tới khi tác vụ kết thúc. Hạn chờ ở phía bạn dừng vòng lặp, không dừng tác vụ: quá trình dựng ảnh vẫn tiếp tục, và bạn có thể truy vấn lại cùng ID đó sau. Một tác vụ kết thúc ở failed sẽ ném ngoại lệ kèm mã lỗi và không bị tính phí.

download tải mọi URL mà tác vụ trả về và ghi xuống ổ đĩa. URL kết quả là điểm bàn giao để nhận ảnh, không phải nơi lưu trữ lâu dài, nên hãy lưu lại những gì bạn muốn giữ. Ví dụ dùng requests cho cả việc tải ảnh lẫn gọi API; hãy dùng một HTTP client xuyên suốt thay vì trộn thêm urllib của thư viện chuẩn.

Thay đổi thiết lập ảnh thế nào?

Mọi thứ đều nằm trong thân yêu cầu. Những trường mà đa số người dùng thay đổi đầu tiên:

Nếu bạn đổi output_format, hãy đổi phần mở rộng .png trong download cho khớp. Danh sách đầy đủ các trường và giới hạn có trong tài liệu tham chiếu GPT Image 2 API.

Chỉnh sửa ảnh từ Python thế nào?

Truyền ảnh tham chiếu dưới dạng URL ngay trong cùng lệnh gọi. Không có endpoint chỉnh sửa riêng; thêm images sẽ biến yêu cầu thành một lần chỉnh sửa, còn mask giới hạn thay đổi trong một vùng:

task_id = submit({
    "model": "gpt-image-2",
    "prompt": "Make the vase deep blue. Keep the table and the light unchanged.",
    "images": [{"image_url": "https://example.com/vase.png"}],
})

URL phải là liên kết HTTPS công khai tới tệp PNG, JPEG hoặc WebP. Bạn có thể gửi tối đa 16 ảnh. Tệp cục bộ và chuỗi base64 đều bị từ chối, nên hãy tải ảnh lên kho lưu trữ của chính bạn trước rồi truyền URL của nó.

Script nên làm gì khi gửi yêu cầu bị hết thời gian chờ?

Đừng gửi lại ngay. Hết thời gian chờ ở lệnh POST không chứng minh yêu cầu đã bị từ chối; tác vụ có thể đã chạy và đã bị tính phí. Hãy kiểm tra các tác vụ gần đây, hoặc chỉ thử lại yêu cầu sau khi xác nhận chưa có tác vụ nào được tạo. Hướng dẫn về tác vụ giải thích cách phân biệt hai trường hợp.

Truy vấn thì khác: hết thời gian chờ khi truy vấn là vô hại. Hãy gọi lại wait với cùng ID.

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

Có dùng OpenAI Python SDK thay thế được không?

Không trực tiếp. API này giao kết quả bất đồng bộ qua một ID tác vụ, trong khi lệnh gọi ảnh của SDK chờ ảnh hoàn chỉnh nằm ngay trong phản hồi. Vài dòng requests như trên là đủ cho toàn bộ quy trình.

Chạy nhiều prompt thế nào?

Gửi từng prompt, lưu tất cả ID tác vụ, rồi truy vấn chúng. Hướng dẫn tạo ảnh theo lô có một phiên bản chịu được việc khởi động lại mà không phải trả tiền hai lần.

gpt-image-2-official có cần code khác không?

Không. Chỉ đổi chuỗi model, không gì khác. Hai ID nhận cùng các trường và trả về cùng một phản hồi tác vụ; chỉ cách tính phí là khác.

Giữ ID tác vụ, phần còn lại chỉ là đường ống

Gửi yêu cầu, lưu ID, truy vấn có hạn chờ và tải những gì được trả về. Mẫu đó là toàn bộ phần tích hợp. Hãy thử một prompt không cần code trong Playground GPT Image 2 trước khi viết script.