Hướng dẫn AI

Tạo và chỉnh sửa hình ảnh với GPT-Image-2.5 thông qua APIMart

Tìm hiểu cách gọi GPT-Image-2.5 thông qua cổng APIMart bằng cURL và Python. Hướng dẫn này giải thích các tuyến Flare và Sunburst, cơ chế tính phí cố định so với tính theo token, cách chuyển văn bản thành hình ảnh và chỉnh sửa dựa trên hình ảnh tham chiếu, cách thăm dò tác vụ bất đồng bộ, xử lý đầu ra và các mẹo thực tế khi triển khai.

17 tháng 9, 2026Thời gian đọc khoảng 23 phút

Tạo và chỉnh sửa hình ảnh với GPT-Image-2.5 qua APIMart

Gateway image2.5 APIMart thực hiện những gì

Gateway image2.5 cung cấp quyền truy cập vào nhóm mô hình tạo và chỉnh sửa GPT Image 2.5 thông qua API APIMart. Thay vì tích hợp thông tin xác thực và định dạng yêu cầu riêng cho từng mô hình hình ảnh, bạn sử dụng một URL cơ sở, một bearer token và endpoint /v1/images/generations theo chuẩn OpenAI.

API hoạt động không đồng bộ. Yêu cầu tạo ảnh trả về ID tác vụ thay vì hình ảnh trực tiếp. Sau đó, ứng dụng của bạn sẽ thăm dò endpoint tác vụ cho đến khi quá trình hoàn tất hoặc thất bại. Các tác vụ thành công chứa những URL đầu ra tạm thời, cần được tải xuống trước khi hết hạn.

APIMart là dịch vụ được tài liệu trong repository. Endpoint gpt-image-2.5-ext là tuyến chuyển tiếp của bên thứ ba, trong khi gpt-image-2.5-flare và gpt-image-2.5-sunburst là các tuyến tính phí theo token. Hãy xác minh giới hạn và giá hiện tại trước khi chạy trong môi trường production.

Tính năng chính

Một URL cơ sở API: Các yêu cầu sử dụng https://api.apimart.ai/v1.
Hai biến thể mô hình: Chọn Flare để tạo ảnh hằng ngày và bản nháp theo lô, hoặc Sunburst để chỉnh sửa chính xác và tạo tài sản phục vụ production.
Hai hình thức tính phí: Tuyến chuyển tiếp tính phí theo từng hình ảnh được phân phối, trong khi các tuyến chính thức tính phí theo token.
Xử lý không đồng bộ: Gửi yêu cầu và thăm dò GET /v1/tasks/{task_id} để theo dõi tiến trình.
Nhiều cấp đầu ra: Tuyến chuyển tiếp hỗ trợ 1K, 2K và 4K.
Bố cục linh hoạt: Chọn một trong mười tỷ lệ khung hình hoặc sử dụng auto.
Tạo ảnh dựa trên ảnh tham chiếu: Cung cấp tối đa 16 mục trong image_urls cho công việc chuyển ảnh thành ảnh hoặc chỉnh sửa.
Lô nhỏ: Yêu cầu từ một đến bốn hình ảnh được phân phối bằng n trên tuyến chuyển tiếp.

Chọn đúng tuyến mô hình

Tuyến chuyển tiếp tính phí theo hình ảnh

Sử dụng model: "gpt-image-2.5-ext" khi bạn muốn tính phí cố định cho mỗi hình ảnh được phân phối. Chọn biến thể nền bằng version: "flare" hoặc version: "sunburst".

flare phù hợp với việc tạo ảnh số lượng lớn, hình ảnh hằng ngày và bản nháp.
sunburst phù hợp với việc chỉnh sửa và công việc production dựa trên ảnh tham chiếu.

Repository ghi nhận mức giá $0.0085 cho mỗi hình ảnh 1K được phân phối của cả hai biến thể vào ngày 16 tháng 9 năm 2026. Repository cũng ghi nhận mức $0.014 cho 2K, $0.021 cho 4K Flare và khuyến nghị kiểm tra giá trực tiếp cho 4K Sunburst. Đây là các mức giá được ghi nhận tại thời điểm quan sát, không phải cam kết cố định vĩnh viễn.

Các tuyến chính thức tính phí theo token

Sử dụng trực tiếp gpt-image-2.5-flare hoặc gpt-image-2.5-sunburst để tính phí theo token. Các tuyến này không dùng trường version và hỗ trợ các mức chất lượng low, medium, high, xhigh và max. Tuyến chính thức cũng hỗ trợ kích thước pixel chính xác.

Một nguyên tắc thực tế là sử dụng tuyến chuyển tiếp khi chi phí dự đoán được cho mỗi hình ảnh là yếu tố quan trọng, và cân nhắc tuyến chính thức khi cần các tùy chọn kiểm soát chất lượng hoặc kích thước chính xác của tuyến này.

Phạm vi đầu ra mẫu

Repository minh họa các prompt cho ảnh sản phẩm, chân dung, kiến trúc, tài sản UI, hình minh họa, nghệ thuật trò chơi, ảnh đồ ăn và ảnh macro. Các hình ảnh được cung cấp dưới đây minh họa loại đầu ra trực quan đi kèm dự án.

Ví dụ đầu ra được tạo bằng GPT Image 2.5

Đầu ra GPT Image 2.5 được tạo thứ hai

Cài đặt và thiết lập

1. Tạo API key

Lấy key từ trang API key của APIMart. Lưu key trong biến môi trường thay vì đặt trực tiếp vào mã nguồn.

export APIMART_API_KEY="your-api-key"

2. Chọn client

cURL không yêu cầu dependency của dự án nào ngoài bản cài đặt dòng lệnh tiêu chuẩn. Với ví dụ Python, hãy cài đặt package requests:

python -m pip install requests

Repository cũng bao gồm ví dụ JavaScript cho Node.js 18 trở lên, trong đó fetch khả dụng trên toàn cục.

3. Hiểu các header của yêu cầu

Gửi API key trong header Authorization. Các ví dụ về tuyến chuyển tiếp cũng sử dụng header phiên bản phản hồi và một khóa idempotency duy nhất.

Authorization: Bearer $APIMART_API_KEY
Content-Type: application/json
X-APIMart-Response-Version: 2026-07-27
Idempotency-Key: unique-request-value

Sử dụng lại cùng một khóa idempotency khi thử lại cùng một lần gửi. Tạo khóa mới khi bạn chủ ý muốn tạo một tác vụ hình ảnh mới.

Cách dùng cơ bản: tạo hình ảnh bằng cURL

Yêu cầu sau sử dụng tuyến tính phí theo hình ảnh, chọn Flare và yêu cầu một hình ảnh vuông 1K:

IDEMPOTENCY_KEY="$(uuidgen)"

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-APIMart-Response-Version: 2026-07-27" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "model": "gpt-image-2.5-ext",
    "version": "flare",
    "prompt": "Một góc đọc sách ấm cúng bên cửa sổ vào ngày mưa, đèn bàn ấm áp, ánh sáng điện ảnh",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

Yêu cầu gửi thành công sẽ trả về HTTP 202. Đọc mã định danh tác vụ từ data.id hoặc sử dụng data.poll_url được trả về.

Thăm dò tác vụ

Thay task_01EXAMPLE bằng ID tác vụ được trả về:

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01EXAMPLE \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "X-APIMart-Response-Version: 2026-07-27"

Trạng thái tác vụ lần lượt chuyển qua pending và processing trước khi đạt completed hoặc failed. Phản hồi cũng có thể cung cấp progress, cost và credits_cost. Khi hoàn tất, lấy URL hình ảnh từ result.images[].url và kiểm tra expires_at.

Ví dụ Python đầu-cuối

Ví dụ này gửi một yêu cầu tạo hình ảnh và kiểm tra tác vụ sau mỗi năm giây cho đến khi đạt trạng thái kết thúc:

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
COMMON_HEADERS = {
    "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
    "Content-Type": "application/json",
    "X-APIMart-Response-Version": "2026-07-27",
}

def generate_image(prompt, version="flare", resolution="1K", size="1:1"):
    submit_headers = {
        **COMMON_HEADERS,
        "Idempotency-Key": str(uuid.uuid4()),
    }

    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=submit_headers,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
        timeout=60,
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        task_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        task_response.raise_for_status()
        task = task_response.json()["data"]

        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(f"Tạo hình ảnh thất bại: {task}")

        time.sleep(5)

result = generate_image(
    "Một khu vườn trên cao lúc bình minh, nhiếp ảnh kiến trúc",
    version="flare",
    resolution="1K",
    size="16:9",
)

for image in result["result"]["images"]:
    print(image["url"], image.get("expires_at"))

Đối với ứng dụng khách dùng trong môi trường production, hãy trả về hoặc lưu trữ toàn bộ đối tượng tác vụ để giữ lại thông tin về chi phí, tiến độ, thời hạn và lỗi thay vì chỉ trả về một URL.

Sử dụng hình ảnh tham chiếu để chỉnh sửa

Để tạo hoặc chỉnh sửa hình ảnh dựa trên hình ảnh đầu vào qua tuyến chuyển tiếp, hãy thêm một mảng image_urls. Mảng này có thể chứa tối đa 16 URL hoặc data URL. Kho lưu trữ cho biết hình ảnh tham chiếu không phát sinh khoản phí riêng trên tuyến này.

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "Giữ nguyên nhãn sản phẩm, thay nền bằng màu trắng ngà dịu nhẹ và thêm bóng đổ tự nhiên",
  "image_urls": [
    "https://example.com/source-product.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

Sunburst là biến thể được kho lưu trữ đề xuất cho việc chỉnh sửa chính xác và các tác vụ dựa trên hình ảnh tham chiếu. Hãy sử dụng các URL có thể truy cập hoặc data URL hợp lệ, đồng thời giữ số lượng trong giới hạn được tài liệu hóa.

Tham chiếu các trường yêu cầu cho tuyến chuyển tiếp

model: Bắt buộc. Đặt thành gpt-image-2.5-ext.
version: Chấp nhận flare hoặc sunburst; mặc định là Flare.
prompt: Bắt buộc và không được để trống sau khi loại bỏ khoảng trắng.
resolution: Chấp nhận 1K, 2K hoặc 4K; mặc định là 1K.
size: Chấp nhận auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5 hoặc 21:9.
n: Chấp nhận số nguyên từ 1 đến 4.
image_urls: Mảng tùy chọn chứa tối đa 16 URL tham chiếu hoặc data URL.

Gọi tuyến tính phí theo token

Tuyến chính thức sử dụng cùng đường dẫn tạo hình ảnh nhưng thay đổi ID model, loại bỏ version và thêm thiết lập chất lượng. Ví dụ này chọn Sunburst với chất lượng cao:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Giữ nguyên nhãn sản phẩm, thay nền bằng màu trắng ngà dịu nhẹ và thêm bóng đổ tự nhiên",
    "size": "1:1",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'

Tham khảo tài liệu tham chiếu tuyến chính thức và tài liệu tham chiếu tuyến chuyển tiếp để xem định nghĩa các trường hiện tại.

Mẹo nâng cao để tích hợp đáng tin cậy

Đảm bảo các lần thử lại có tính idempotent. Giữ nguyên khóa idempotency ban đầu nếu một lần gửi bị hết thời gian chờ và bạn không chắc tác vụ đã được tạo hay chưa. Khóa mới có thể tạo thêm một lần tạo ảnh bị tính phí.
Coi việc polling là quy trình bình thường. Xử lý cả hai trạng thái completed và failed. Tránh polling quá nhanh; ví dụ trong repository chờ năm giây giữa các lần kiểm tra.
Sử dụng URL polling được trả về. Phản hồi có data.poll_url, giúp bạn không phải tự xây dựng lại endpoint của tác vụ.
Tải các đầu ra xuống sớm. URL ảnh được tạo chỉ có hiệu lực tạm thời. Sao chép từng đầu ra vào bộ lưu trữ của riêng bạn trước thời điểm expires_at.
Ghi nhận chi phí thực tế. Lưu cost và credits_cost từ phản hồi của tác vụ. Điều này cho phép bạn so sánh mức tính phí thực tế với bảng giá đã công bố.
Xác thực chi phí bằng một yêu cầu có trả phí. Bảng giá và cơ chế định tuyến khuyến mãi có thể thay đổi, vì vậy hãy chạy một bài kiểm tra nhỏ trước khi khởi chạy lô lớn.
Sử dụng tuyến phù hợp. Chọn tuyến chuyển tiếp để có mức phí dự đoán được cho mỗi ảnh và các lô tối đa bốn ảnh. Chọn ID model chính thức khi thứ bậc chất lượng hoặc khả năng kiểm soát pixel chính xác là yếu tố quan trọng.
Chuyển đổi biến thể mà không cần viết lại client. Trên tuyến chuyển tiếp, chỉ thay đổi version giữa flare và sunburst.
Bảo vệ thông tin xác thực. Lưu khóa API trong biến môi trường hoặc trình quản lý bí mật, và không bao giờ để lộ khóa trong mã chạy phía trình duyệt.

Kết luận

Cổng image2.5 của APIMart cung cấp một cách nhất quán để truy cập tính năng tạo và chỉnh sửa ảnh bằng GPT Image 2.5. Hãy bắt đầu với gpt-image-2.5-ext và Flare để tạo ảnh số lượng lớn, ổn định; chuyển sang Sunburst cho công việc chỉnh sửa hoặc dựa trên ảnh tham chiếu; và sử dụng ID model chính thức khi cơ chế tính phí theo token cùng các tùy chọn chất lượng mở rộng phù hợp hơn với tác vụ.

Mẫu tích hợp cốt lõi rất đơn giản: gửi yêu cầu hình ảnh, lưu ID tác vụ được trả về, polling cho đến khi hoàn tất, kiểm tra chi phí được báo cáo và tải mọi kết quả xuống trước khi URL tạm thời hết hạn. Trước khi mở rộng quy mô, hãy xem lại bảng giá APIMart hiện tại và xác thực tuyến đã chọn bằng một yêu cầu có trả phí nhỏ.