GPT Image 2 (Gói đăng ký)

POSThttps://sangtao.ai/api/v2/agents/jobs/create

Tạo ảnh bằng model GPT Image 2 với gói đăng ký của bạn, giá siêu rẻ chỉ từ 100đ/ảnh, nhận lên tới 20 ảnh tham chiếu.

Bất đồng bộ: tạo job, poll tới khi xong, rồi đọc link kết quả. Một job thường mất 30–90 giây.

Headers

X-Api-Keystringbắt buộc

API key của bạn. Tạo ở trang API Key trong tài khoản.

Content-Typestringbắt buộc

application/json

Request

Mỗi job thường cho ra một ảnh, đôi khi hai. Muốn số lượng chắc chắn thì mỗi ảnh một job.

modelstringbắt buộc

Bắt buộc là "chatgpt-image-sangtao"

promptstringbắt buộc

Nội dung cần vẽ. Hãy mô tả đầy đủ cảnh, phong cách, bố cục — một hai từ là không đủ. Prompt ngắn kiểu "blue square" sẽ trả về PROMPT_UNCLEAR.

aspectRatiostringtuỳ chọn

"1:1", "16:9", "9:16"… Cũng có thể ghi tỷ lệ thẳng trong prompt, nên trường này là cách tiện chứ không phải cách duy nhất.

formatstringtuỳ chọnmặc định "png"

"png" hoặc "jpeg"

referenceImagesstring[]tuỳ chọn

Tối đa 20 link, mỗi link bắt đầu bằng http:// hoặc https://. Link phải mở được mà không cần đăng nhập — hệ thống tải thử ngay lúc tạo job và từ chối luôn, thay vì để job chạy rồi mới hỏng. Một số CDN chặn truy cập từ máy chủ khác, nên link mở được trên trình duyệt của bạn vẫn có thể bị từ chối. Nếu ảnh chỉ nằm trên máy bạn, hãy upload trước: Upload ảnh sẽ trả về URL dùng được ở đây.

resolutionstringtuỳ chọnmặc định "1K"

"1K" hoặc "2K". 2K cho cạnh dài khoảng 2048px

requireTransparentbooltuỳ chọn

Yêu cầu nền trong suốt

dpiinttuỳ chọn

1–1200. Chỉ là metadata in ấn — KHÔNG đổi số pixel

idempotencyKeystringtuỳ chọn

Bảo vệ khi retry: gọi lại cùng key sẽ trả về đúng jobId cũ, không tạo job mới và không trừ tiền lần hai. MỖI job muốn tạo thật thì sinh một giá trị MỚI — hệ thống chỉ so key chứ không so prompt, nên dùng lại key sẽ nhận về ảnh cũ mà không báo lỗi gì. Key có hiệu lực khoảng năm phút. Thường dùng một UUID cho mỗi job, hoặc mã đơn hàng của bạn.

Response

jobIdstring

ID của job. Truyền vào GET /jobs/{jobId} để poll lấy kết quả. Hãy lưu kèm đơn hàng hoặc bản ghi của bạn — đó là thứ duy nhất bạn nắm được về job sau đó.

statusstring

Luôn là "WaitingForAgent" — job mới vào hàng đợi, chưa chạy.

chargeSourcestring

"Subscription" nếu gói tháng trả, "Credit" nếu trừ vào số dư.

creditCostnumber

Chi phí job này. Bằng 0 khi gói tháng đã trả.

quotaRemainingnumber

Quota gói còn lại sau job này. null nếu trả bằng credit.

queuePositionnumber

Vị trí trong hàng đợi. 0 nghĩa là chạy ngay.

queueDepthnumber

Sức chứa tối đa của hàng đợi.

runningJobsnumber

Số job của bạn đang chạy.

concurrencynumber

Số job chạy song song tối đa. Job thừa xếp hàng chứ không lỗi.

capReasonstring

Lý do của con số concurrency — ví dụ gói thuê bao, hay công suất máy.

runningOnFallbackbool

Job có đang chạy trên nhóm máy dự phòng không. Bình thường là null.

Lỗi lúc chạy

Job hỏng trả về status "error" kèm failureKind. Đây là trường quyết định retry có ích hay không — retry một lỗi cố định chỉ đốt thêm tiền.

failureKind	Nghĩa	Retry?
PROMPT_UNCLEAR	Mô tả quá mơ hồ	Không — đổi prompt
CONTENT_REJECTED	Vi phạm chính sách nội dung	Không — đổi prompt
TRANSPARENT_CREATION_FAILED	Yêu cầu nền trong suốt nhưng ảnh ra không có alpha	Không — ghi rõ hơn trong prompt
REFERENCE_DOWNLOAD_FAILED	Không tải được ảnh tham chiếu	Không — sửa link
GENERATION_TIMEOUT	Quá giờ chờ	Có — thường được
QUOTA_EXHAUSTED	Hệ thống tạm thời quá tải	Có — sau vài giờ
SESSION_EXPIRED	Lỗi phía chúng tôi, không phải do request của bạn	Liên hệ hỗ trợ
INVALID_PAYLOAD	Lỗi phía chúng tôi	Liên hệ hỗ trợ

POST/agents/jobs/create

curl -X POST \
  https://sangtao.ai/api/v2/agents/jobs/create \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chatgpt-image-sangtao",
    "prompt": "A vintage travel poster of Ha Long Bay at sunset",
    "aspectRatio": "9:16",
    "resolution": "2K"
  }'

{
  "success": true,
  "data": {
    "jobId": "acff47cbfacf4e27bbc08770c9ea246d",
    "status": "WaitingForAgent",
    "chargeSource": "Subscription",
    "creditCost": 0.0,
    "quotaRemaining": 966,
    "queuePosition": 0,
    "queueDepth": 50,
    "runningJobs": 0,
    "concurrency": 10,
    "capReason": "gói thuê bao",
    "runningOnFallback": null
  },
  "error": null,
  "errorCode": null
}

POST/agents/jobs/create

curl -X POST \
  https://sangtao.ai/api/v2/agents/jobs/create \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chatgpt-image-sangtao",
    "prompt": "A vintage travel poster of Ha Long Bay at sunset",
    "aspectRatio": "9:16",
    "resolution": "2K"
  }'

{
  "success": true,
  "data": {
    "jobId": "acff47cbfacf4e27bbc08770c9ea246d",
    "status": "WaitingForAgent",
    "chargeSource": "Subscription",
    "creditCost": 0.0,
    "quotaRemaining": 966,
    "queuePosition": 0,
    "queueDepth": 50,
    "runningJobs": 0,
    "concurrency": 10,
    "capReason": "gói thuê bao",
    "runningOnFallback": null
  },
  "error": null,
  "errorCode": null
}

Trang trướcTheo dõi Job Trang sauTạo ảnh AI