Tài liệu API GPT Image Hub

Tất cả các điểm cuối v1 ngoại trừ danh sách mô hình đều yêu cầu khóa API trong tiêu đề Authorization. Khóa thô được hiển thị một lần tại thời điểm tạo; máy chủ chỉ lưu trữ một hàm băm.

Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Điểm cuối models trả về ID mô hình, nhà cung cấp, tỷ lệ khung hình được hỗ trợ, mức chất lượng được hỗ trợ, giới hạn hình ảnh tham chiếu và số tín dụng cho mỗi hình ảnh.

curl https://www.gptimagehub.com/api/v1/models

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

Điểm cuối tín dụng trả về số dư, loại tài khoản và thời hạn tín dụng sắp hết hạn cho người dùng sở hữu khóa API.

curl https://www.gptimagehub.com/api/v1/credits \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Theo mặc định, điểm cuối tạo hình ảnh sẽ chờ đến khi hoàn tất. Đặt async thành true để nhận ngay generation id và thăm dò /api/v1/generations/:generationId để lấy kết quả. Tín dụng được trừ trước khi nhà cung cấp tạo ảnh và được hoàn lại tự động khi nhà cung cấp gặp lỗi hoặc trả về ít ảnh hơn số lượng yêu cầu.

Yêu cầu JSON

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a transparent perfume bottle on black marble",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

Tác vụ bất đồng bộ

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-hero-image" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo with premium studio lighting",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
    "async": true
  }'

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "queued",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "created_at": "2026-04-30T08:00:00.000Z",
  "images": [],
  "usage": {
    "credits": 0,
    "credits_requested": 7
  },
  "poll_url": "https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id"
}

Yêu cầu kèm ảnh tham chiếu

curl https://www.gptimagehub.com/api/v1/images/generations \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=Use the reference image and render it as a premium studio product shot" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "n=1" \
  -F "reference_image=@./reference.png"

Phản hồi

{
  "object": "image_generation",
  "id": "clx_generation_log_id",
  "status": "succeeded",
  "model": "gpt-image-2",
  "aspect_ratio": "1:1",
  "quality": "1K",
  "images": [
    {
      "id": "clx_image_id",
      "object": "image",
      "url": "https://cdn.example.com/generations/user/image.png",
      "created_at": "2026-04-30T08:00:00.000Z"
    }
  ],
  "usage": {
    "credits": 7
  },
  "balance": {
    "credits": 113,
    "account_type": "PRO",
    "next_expiration": null
  }
}

Sử dụng id do điểm cuối tạo ảnh trả về để truy xuất nhật ký đã lưu và URL hình ảnh. Khóa API chỉ có thể đọc các lượt tạo ảnh thuộc cùng một người dùng.

curl https://www.gptimagehub.com/api/v1/generations/clx_generation_log_id \
  -H "Authorization: Bearer gih_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "error": {
    "message": "Invalid request body",
    "code": "invalidRequest"
  }
}

• Quá trình tạo đồng bộ có thể chạy tối đa 800 giây trên production.
• n phải nằm trong khoảng từ 1 đến 4.
• Ảnh tham chiếu hỗ trợ PNG, JPG, JPEG, và WebP. Toàn bộ request, bao gồm tất cả ảnh tham chiếu, phải dưới 4.5MB (tổng dung lượng các ảnh phải dưới 4MB). Các request lớn hơn sẽ bị nền tảng lưu trữ từ chối với phản hồi dạng plain-text 413 trước khi đến được API, vì vậy hãy thay đổi kích thước hoặc nén ảnh trước.
• Số lượng ảnh tham chiếu tối đa được xác định bởi reference_image_limit của từng model.
• Giới hạn tỷ lệ (rate limits): 60 request tạo mỗi phút cho mỗi API key và 120 request mỗi phút cho mỗi địa chỉ IP. Mọi response đều đi kèm các header RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset; mã 429 cũng đi kèm Retry-After.
• Để thử lại quá trình tạo một cách an toàn, hãy gửi header Idempotency-Key (tối đa 120 ký tự). Việc gửi lại cùng một key với cùng API key sẽ trả về kết quả tạo ban đầu thay vì tính phí thêm lần nữa.
• Chế độ async trả về 202 kèm theo poll_url. Webhook hiện chưa được hỗ trợ.