Sáng tạo

GPT Image

Tạo ảnh bằng model GPT Image mới nhất.

POSThttps://api.sangtao.ai/v2/images/generations

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 trả về 1 ảnh, đôi khi 2 để A/B testing.

modelstringbắt buộc

Model tạo ảnh. gpt-image-latest luôn là GPT Image mới nhất; gpt-image-2.6 giữ cố định phiên bản này.

Giá trị nhận:gpt-image-latestgpt-image-2.6

promptstringbắt buộc

Nội dung cần vẽ — cảnh, phong cách, bố cục. Một hai từ (kiểu "blue square") sẽ trả về PROMPT_UNCLEAR.

serverstringtuỳ chọnmặc định "standard"

Nơi chạy job. Bỏ trống để dùng mặc định.

Giá trị nhận:standard

aspectRatiostringtuỳ chọnmặc định "auto"

"auto" để model tự chọn; W:H khác cũng được (mỗi số 1–100, không dẹt hơn 3:1).

Gợi ý:auto1:11:33:11:22:19:1616:910:1616:102:33:23:44:34:55:4

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

Định dạng file ảnh.

Giá trị nhận:pngjpeg

referenceImagesstring[]tuỳ chọn

Tối đa 20 link ảnh (http/https) làm tham chiếu. Link không tồn tại bị từ chối trước khi khoá credit. Ảnh trên máy bạn: upload trước.

resolutionstringtuỳ chọnmặc định "original"

Độ phân giải ảnh. original giữ nguyên ảnh của model (16:9 là 1672×941); 1k / 2k cho cạnh dài khoảng 1024 / 2048px.

Giá trị nhận:original1k2k

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

Gửi lại cùng khoá, cùng nội dung trong 24 giờ sẽ nhận lại đúng job cũ (idempotentReplay: true), không trừ tiền lần hai; nội dung khác thì nhận 422 IDEMPOTENCY_KEY_REUSED. Mỗi ảnh mới một khoá mới (ví dụ UUID) — chỉ gửi lại khoá cũ khi thử lại đúng request đó. Dùng header Idempotency-Key cũng được.

webhookUrlstringtuỳ chọn

URL https công khai (cổng 443) để nhận kết quả của job này khi xong — xem Webhook. URL sai trả 422 INVALID_WEBHOOK_URL, trước khi tạo job hay trừ tiền

webhookSecretstringtuỳ chọn

Dùng để ký các lần giao đó (X-Sangtao-Signature). Tối đa 200 ký tự. Không gửi thì không có chữ ký

Thiếu trường hoặc giá trị sai bị từ chối ngay, chưa tạo job, chưa khoá credit, với mã 422 chứ không phải 400, kèm errorCode: MODEL_REQUIRED, PROMPT_REQUIRED, MODEL_WRONG_CATEGORY, SERVER_NOT_FOUND, INVALID_ASPECT_RATIO, INVALID_FORMAT, INVALID_RESOLUTION (4k là RESOLUTION_NOT_SUPPORTED), INVALID_DPI, REFERENCE_IMAGE_UNREACHABLE, INVALID_WEBHOOK_URL (webhookUrl), hoặc IDEMPOTENCY_KEY_REUSED (idempotencyKey đã dùng cho nội dung khác). Tên model không tồn tại trả 404 MODEL_NOT_FOUND. Sai kiểu dữ liệu (dpi: "abc") trả 400 VALIDATION_ERROR, details[0].code là INVALID_TYPE.

Response

jobIdstring

ID của job. Truyền vào GET /images/generations/{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

"WaitingForAgent" với job mới — đã vào hàng đợi, chưa chạy. Khi gọi lại cùng key thì là trạng thái hiện tại của job: có thể đã là "Processing" hoặc "complete".

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ả. Khi gọi lại cùng key là chi phí của job cũ — không trừ lần nữa.

quotaRemainingnumber

Quota gói còn lại sau job này. null nếu trả bằng credit; null khi gọi lại cùng key (idempotentReplay).

queuePositionnumber

Số job chưa được máy nhận đang đứng trước job này — tính cả job sắp chạy trong vài giây tới. Cùng nghĩa với GET /jobs/{id}. Muốn biết job có chạy ngay không, xem runningJobs < concurrency. null khi gọi lại cùng key (idempotentReplay).

queueDepthnumber

Sức chứa tối đa của hàng đợi. null khi gọi lại cùng key (idempotentReplay).

runningJobsnumber

Số job của bạn đang chạy. null khi gọi lại cùng key (idempotentReplay).

concurrencynumber

Số job chạy song song tối đa. Job thừa xếp hàng chứ không lỗi. null khi gọi lại cùng key (idempotentReplay).

capReasonstring

Lý do của con số concurrency. null khi gọi lại cùng key (idempotentReplay).

Giá trị nhận:subscription planaccount limitworker capacitysystem default

runningOnFallbackbool

Job có đang chạy trên nhóm máy dự phòng không. Bình thường là null; null khi gọi lại cùng key (idempotentReplay).

modelstring

Tên model đúng như bạn gửi, ví dụ "gpt-image-latest".

resolvedModelstring

Model thực sự chạy job, ví dụ "gpt-image-2.6". Chốt lúc tạo job: sau này gpt-image-latest chuyển sang bản mới hơn thì job này vẫn ghi bản nó đã chạy.

serverstring

Server chạy job: "standard".

idempotentReplaybool

Chỉ có (true) khi đây là lần gọi lại cùng idempotencyKey: job đã tạo từ trước, không tạo thêm, không trừ thêm. Lần đầu không có trường này.

Sau đó poll bằng jobId tới khi status là "complete" hoặc "error" — trang tiếp theo: GET /images/generations/{jobId}.

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/images/generations

curl -X POST \
  https://api.sangtao.ai/v2/images/generations \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-latest",
    "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": "subscription plan",
    "runningOnFallback": null,
    "model": "gpt-image-latest",
    "resolvedModel": "gpt-image-2.6",
    "server": "standard"
  },
  "error": null,
  "errorCode": null
}

POST/images/generations

curl -X POST \
  https://api.sangtao.ai/v2/images/generations \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-latest",
    "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": "subscription plan",
    "runningOnFallback": null,
    "model": "gpt-image-latest",
    "resolvedModel": "gpt-image-2.6",
    "server": "standard"
  },
  "error": null,
  "errorCode": null
}

Trang trướcModels Trang sauLấy kết quả ảnh