Dự án này cung cấp gì
Thư viện Prompt image2.5 là tập hợp thực tiễn gồm 12 prompt đã được chạy qua GPT Image 2.5 và xuất bản cùng với hình ảnh kết quả. Mỗi công thức ghi lại prompt, phiên bản mô hình, tỷ lệ khung hình và đầu ra, giúp bạn dễ đánh giá một prompt trước khi điều chỉnh cho ứng dụng của riêng mình.
Các ví dụ sử dụng endpoint tương thích OpenAI của APIMart tại https://api.apimart.ai/v1. Tuyến chuyển tiếp hoạt động bất đồng bộ: ứng dụng của bạn gửi yêu cầu tạo ảnh, nhận ID tác vụ, truy vấn endpoint của tác vụ và tải ảnh xuống sau khi quá trình xử lý hoàn tất.
Tính năng chính
- Quy trình tạo ảnh tương thích OpenAI: yêu cầu được gửi đến
POST /v1/images/generations. - Hai biến thể chuyển tiếp: dùng
version: "flare"để tạo ảnh hằng ngày hoặcversion: "sunburst"cho công việc chỉnh sửa và dựa trên ảnh tham chiếu. - Nhiều mức đầu ra: chọn
1K,2Khoặc4K. - Khung hình linh hoạt: dùng
autohoặc một trong mười tỷ lệ khung hình được hỗ trợ, gồm1:1,16:9,9:16và4:3. - Đầu ra hàng loạt: yêu cầu từ một đến bốn ảnh bằng
n. - Hỗ trợ ảnh tham chiếu: cung cấp tối đa 16 URL hoặc data URL trong
image_urls. - Báo cáo chi phí theo lần gọi: dữ liệu tác vụ hoàn tất bao gồm
costvàcredits_cost. - Thử lại có tính lũy đẳng: API chấp nhận header
Idempotency-Keyđể giúp ngăn việc xử lý trùng lặp khi gửi lại cùng một yêu cầu.
Chọn đúng tuyến mô hình
APIMart cung cấp cả tuyến GPT Image 2.5 chuyển tiếp và chính thức. Các trường yêu cầu và cách tính phí của chúng khác nhau, vì vậy hãy chọn tuyến trước khi viết phần tích hợp.
Tuyến chuyển tiếp tính phí theo ảnh
Đặt model thành gpt-image-2.5-ext và thêm version: "flare" hoặc version: "sunburst". Đây là tuyến được các ví dụ trong thư viện sử dụng và tính phí theo từng ảnh được phân phối.
flare: phù hợp để tạo ảnh hằng ngày và dựng bản nháp hàng loạt.sunburst: phù hợp với chỉnh sửa chính xác và công việc cần giữ nguyên ảnh tham chiếu, vật thể, logo hoặc nhãn sản phẩm.
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. Không gửi trường version với các ID mô hình này. Tuyến chính thức tính phí theo token và hỗ trợ thang chất lượng từ low đến max, cùng với kích thước pixel chính xác.
Không trộn lẫn định dạng tuyến. Bí danh
gpt-image-2.5-extcần bộ chọn phiên bản, còn các ID mô hình chính thức không được kèm bộ chọn này.
Cài đặt và thiết lập
1. Tạo và nạp tiền vào tài khoản
Lấy khóa API từ trang khóa APIMart. Theo repository, dịch vụ không có hạn ngạch miễn phí và hỗ trợ nạp tiền từ $1.
2. Lưu khóa trong biến môi trường
export APIMART_API_KEY="your-api-key"Tránh đặt khóa trực tiếp trong mã nguồn ứng dụng hoặc commit khóa vào hệ thống quản lý phiên bản.
3. Cài đặt dependency Python
Ví dụ Python sử dụng gói bên thứ ba requests.
python -m pip install requestsNếu thích curl, hãy đảm bảo shell của bạn có curl và một trình tạo UUID như uuidgen.
Gửi yêu cầu tạo ảnh đầu tiên bằng curl
Yêu cầu sau tạo một ảnh vuông 1K với biến thể chuyển tiếp flare:
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": "A cozy reading nook beside a window on a rainy day, warm table lamp, cinematic lighting",
"size": "1:1",
"resolution": "1K",
"n": 1
}'Yêu cầu gửi thành công 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ề.
Truy vấn tác vụ
curl --request GET \
--url "https://api.apimart.ai/v1/tasks/TASK_ID" \
--header "Authorization: Bearer $APIMART_API_KEY" \
--header "X-APIMart-Response-Version: 2026-07-27"Tác vụ thường chuyển từ pending sang processing, sau đó kết thúc ở trạng thái completed hoặc failed. Khi hoàn tất, lấy các URL đã tạo từ result.images[].url.
URL ảnh đã tạo có chứa dấu thời gian
expires_at. Hãy tải xuống và lưu từng tệp trước khi URL hết hạn.
Xây dựng client Python đầu-cuối
Ví dụ này gửi một yêu cầu, kiểm tra lỗi HTTP, truy vấn mỗi năm giây và trả về bản ghi tác vụ đã hoàn tất. Mỗi lần tạo mới sẽ tạo một khóa lũy đẳng mới.
import os
import time
import uuid
import requests
BASE_URL = "https://api.apimart.ai/v1"
API_KEY = os.environ["APIMART_API_KEY"]
COMMON_HEADERS = {
"Authorization": f"Bearer {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,
timeout=60,
json={
"model": "gpt-image-2.5-ext",
"version": version,
"prompt": prompt,
"size": size,
"resolution": resolution,
"n": 1,
},
)
response.raise_for_status()
task_id = response.json()["data"]["id"]
while True:
poll_response = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=COMMON_HEADERS,
timeout=60,
)
poll_response.raise_for_status()
task = poll_response.json()["data"]
if task["status"] == "completed":
return task
if task["status"] == "failed":
raise RuntimeError(f"Generation failed: {task}")
time.sleep(5)
result = generate_image(
"Ảnh sản phẩm chủ đạo trong studio: một tách espresso bằng gốm mờ trên bệ đá ấm màu, ánh sáng cửa sổ dịu, hiệu ứng ống kính 85mm, phông nền màu be tối giản, bóng đổ rõ nét"
)
print("Chi phí:", result.get("cost"))
for image in result["result"]["images"]:
print("URL hình ảnh:", image["url"])
print("Hết hạn lúc:", image.get("expires_at"))Thử lại an toàn
Nếu yêu cầu gửi bị hết thời gian chờ hoặc nhận được phản hồi có thể thử lại, hãy gửi lại cùng một yêu cầu logic với cùng Idempotency-Key. Sử dụng khóa mới khi cố ý tạo hình ảnh mới. Nếu cần tạo lại một tác vụ đã hoàn tất vì nguồn hoặc tham chiếu đã thay đổi, cũng hãy sử dụng khóa mới.
Tìm hiểu các trường chính của yêu cầu
model: bắt buộc; sử dụnggpt-image-2.5-extcho tuyến chuyển tiếp.version:flarehoặcsunburst; mặc định làflare.prompt: bắt buộc và phải chứa văn bản không chỉ gồm khoảng trắng.resolution:1K,2Khoặc4K; mặc định là1K.size: mặc định làauto. Các tỷ lệ được hỗ trợ gồm1:1,16:9,9:16,4:3,3:4,3:2,2:3,5:4,4:5và21:9.n: số lượng hình ảnh, từ một đến bốn trên tuyến chuyển tiếp.image_urls: mảng tùy chọn chứa tối đa 16 URL hình ảnh hoặc data URL.
Viết prompt đáng tin cậy hơn
Thư viện xem prompt là một bản mô tả ngắn gọn cho quá trình sản xuất thay vì danh sách các tính từ mơ hồ. Một cấu trúc hữu ích gồm chủ thể, chất liệu, ánh sáng, bố cục hoặc ống kính và phong cách hoàn thiện.
- Nêu rõ chủ thể: xác định vật thể, người, cảnh hoặc môi trường chính.
- Chỉ định chất liệu vật lý: sử dụng các cụm như
gốm mờ,kính mờhoặckết xuất đất sét. - Thiết lập ánh sáng: mô tả ánh sáng cửa sổ dịu, ánh sáng tự nhiên từ bên hông, ánh sáng studio high-key hoặc đèn nền ấn tượng.
- Cố định bố cục: nêu bố cục căn giữa, flat lay từ trên cao, bố cục điện ảnh góc rộng hoặc cách sắp xếp mong muốn khác.
- Thêm ngôn ngữ về ống kính: các thuật ngữ như
85mm,24mm,macrovàfocus stackedcó thể định hướng phối cảnh và chi tiết. - Chọn phong cách hoàn thiện: các cụm như chi tiết giàu tính hội họa, ảnh sản phẩm thương mại hoặc đường nét vector sắc gọn giúp kiểm soát cách thể hiện hình ảnh.
Ví dụ:
Ảnh sản phẩm mỹ phẩm: chai thủy tinh mờ chứa serum màu hổ phách,
những giọt nước trên bề mặt, phông nền hồng nhạt liền mạch,
ảnh sản phẩm thương mại độ chi tiết cao
Sử dụng hình ảnh tham chiếu
Đối với công việc chuyển đổi hình ảnh hoặc dựa trên hình ảnh tham chiếu, hãy thêm mảng image_urls vào yêu cầu chuyển tiếp. Tuyến này chấp nhận tối đa 16 hình ảnh tham chiếu.
{
"model": "gpt-image-2.5-ext",
"version": "sunburst",
"prompt": "Giữ nguyên sản phẩm và nhãn, thay phông nền bằng màu trắng ngà dịu, đồng thời thêm bóng đổ tự nhiên",
"image_urls": [
"https://example.com/product-reference.jpg"
],
"size": "1:1",
"resolution": "2K",
"n": 1
}Hãy sử dụng các URL tham chiếu ổn định và có thể truy cập. Nếu một tác vụ thất bại vì URL tham chiếu đã hết hạn, hãy lưu trữ lại hình ảnh trên máy chủ khác và gửi một tác vụ mới bằng khóa idempotency mới.
Gọi tuyến chính thức
Tuyến chính thức sử dụng ID mô hình trực tiếp và thiết lập quality thay vì bộ chọn version của tuyến chuyển tiếp.
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 phông nền bằng màu trắng ngà dịu, thêm bóng đổ tự nhiên",
"size": "1:1",
"resolution": "1k",
"quality": "high",
"n": 1
}'Tham khảo tài liệu về route chính thức và tài liệu về route chuyển tiếp để xem thông tin chi tiết hiện tại về các trường.
Mẹo nâng cao cho môi trường production
Tách việc gửi yêu cầu khỏi quá trình xử lý
Lưu ID tác vụ được trả về vào hàng đợi hoặc cơ sở dữ liệu thay vì giữ một yêu cầu web mở. Worker nền có thể kiểm tra các tác vụ chưa hoàn tất và lưu kết quả đã hoàn thành.
Sử dụng khoảng thời gian kiểm tra vừa phải
Các ví dụ trong repository kiểm tra cứ mỗi năm giây. Tránh các vòng lặp quá dày gây lưu lượng không cần thiết. Với khối lượng công việc lớn hơn, hãy thêm thời gian chờ tăng dần khi tác vụ vẫn đang chờ hoặc được xử lý.
Ghi nhận chi phí thực tế
Lưu cost hoặc credits_cost từ mọi tác vụ đã hoàn tất. Nhờ đó, bạn có bản ghi chi tiêu cho từng lần gọi thay vì chỉ dựa vào ước tính.
README ghi nhận mức giá quan sát được của route chuyển tiếp là $0.0085 cho mỗi ảnh 1K được phân phối, $0.014 cho 2K và $0.021 cho 4K flare. Giá 4K sunburst chưa được cố định trong bảng. Các số liệu này được ghi nhận vào tháng 9 năm 2026, vì vậy hãy kiểm tra giá trực tiếp trước khi lập ngân sách hoặc mở rộng quy mô.
Tải kết quả xuống ngay
Đừng xem result.images[].url là nơi lưu trữ lâu dài. Hãy tải tệp xuống trước expires_at, sau đó chuyển tệp vào hệ thống lưu trữ do ứng dụng của bạn kiểm soát.
Bắt đầu nhỏ trước khi mở rộng
Xác thực một prompt ở 1K với n: 1. Chỉ tăng độ phân giải hoặc yêu cầu nhiều đầu ra sau khi chủ thể, bố cục và phong cách đã ổn định.
Điều chỉnh tỷ lệ khung hình theo nơi sử dụng
1:1cho biểu tượng, thẻ sản phẩm và nội dung mạng xã hội hình vuông.16:9cho cảnh điện ảnh, bảng điều khiển và tiêu đề bài thuyết trình.9:16cho bố cục dọc trên thiết bị di động và mạng xã hội.4:3cho hình minh họa biên tập và ảnh đồ ăn.3:4cho ảnh chân dung và bố cục thời trang.
Khắc phục sự cố
401hoặc khóa API không hợp lệ: sao chép lại khóa và kiểm tra khoảng trắng hoặc ký tự xuống dòng. Header phải sử dụngAuthorization: Bearer $APIMART_API_KEY.- Lỗi số dư hoặc tín dụng: nạp tiền vào tài khoản; repository cho biết không có hạn ngạch dự phòng miễn phí.
- Phản hồi
429: giảm mức độ đồng thời, tăng thời gian chờ và thử lại cùng yêu cầu gửi với cùng khóa idempotency. 400hoặc không tìm thấy model: xác minh rằnggpt-image-2.5-extcó kèm phiên bản và ID model chính thức trực tiếp thì không.- Trạng thái tác vụ là
failed: kiểm tra xem prompt có bị từ chối hay URL tham chiếu đã hết hạn không. Sửa đầu vào và gửi một tác vụ mới với khóa mới. - URL đầu ra không còn hoạt động: URL tạm thời có thể đã hết hạn. Các đầu ra hoàn tất trong tương lai nên được tải xuống ngay.
Kết luận
Image2.5 Prompt Gallery trình bày quy trình có thể lặp lại để tạo tài sản với GPT Image 2.5: chọn đúng route, viết prompt theo phong cách production, gửi yêu cầu bất đồng bộ, kiểm tra ID tác vụ, ghi nhận chi phí được báo cáo và tải kết quả xuống trước khi hết hạn. Hãy bắt đầu với một ảnh 1K, xác minh chất lượng và chi phí, sau đó mở rộng lên độ phân giải cao hơn, xử lý theo lô hoặc các quy trình sunburst dựa trên ảnh tham chiếu.