Tạo ảnh (Native / Upscale)

KuaiAPI có hai nhóm ảnh. Tên model giống nhau; nhóm quyết định giá, đặc tính đầu ra và C2PA.

Nhóm	Phù hợp	Giá	C2PA
GPT-Image (Native)	Tạo ảnh từ văn bản, sửa ảnh, vẽ lại cục bộ	0.15/ảnh (1K/2K/4K)	Có
GPT-Image-Upscale (Upscale)	Phóng to ảnh, upscale sinh tạo, vẽ lại theo ảnh tham chiếu	1K 0.05 / 2K 0.08 / 4K 0.10	Không

Một key chỉ thuộc một nhóm

Key native chỉ dùng được nhóm native; key upscale chỉ dùng được nhóm upscale. Tên model giống nhau nhưng giá, đầu ra và C2PA khác nhau.

01 Base URL

https://kuaiapi.net/v1

• Dùng tên miền gốc kuaiapi.net, không dùng www (www chuyển POST /v1/images/* bằng 301 thành GET và lỗi).
• URL đã có /v1; không thêm /v1 lần nữa.
• Mọi request gửi Authorization: Bearer sk-....

02 Model

Cả hai nhóm hiện cung cấp 6 model ảnh:

Model	Ghi chú
gpt-image-2.5-flare	Model chính, đủ các mức chất lượng
gpt-image-2.5-sunburst	Dòng 2.5 thứ hai
gpt-image-2.6-flare	Dòng 2.6, nhiều định dạng đầu ra hơn
gpt-image-2.6-sunburst	Dòng 2.6 thứ hai
gpt-image-2.5	Tên chung của 2.5
gpt-image-2	Model thế hệ 2

Dùng danh sách do GET /v1/models trả về cho key của bạn. Model không có trong nhóm sẽ trả 404 / không tìm thấy model.

03 Tạo ảnh từ văn bản: JSON

curl --fail-with-body --max-time 600 "https://kuaiapi.net/v1/images/generations" \
  -H "Authorization: Bearer $KUAiapi_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Ngọn hải đăng nhỏ màu xanh trên nền trắng",
    "size": "2048x2048",
    "quality": "medium",
    "n": 1,
    "response_format": "url"
  }'

Tham số

Tham số	Giá trị	Ghi chú
model	Tên đầy đủ trong danh mục nhóm	Không tự thêm hậu tố chất lượng
prompt	Chuỗi không rỗng	Mô tả ảnh đích
size	1K / 2K / 4K, hoặc pixel	Pixel phải là số nguyên dương, bội số của 16, ngăn bằng x
quality	low / medium / high; 2.5 thêm xhigh / max	Mặc định medium; mức cao lâu hơn
n	Số nguyên dương; bắt đầu với 1	Số ảnh
response_format	url / b64_json	Đọc data[].url / data[].b64_json

Kích thước thường dùng:

Mục tiêu	Giá trị
Vuông 1K / 2K / 4K	1024x1024 / 2048x2048 / 4096x4096
Ngang / dọc	1536x1024 / 1024x1536
16:9 / 9:16	2048x1152 / 1152x2048

Có thể dùng size=1K, 2K, 4K và hệ thống tự đổi sang pixel; ảnh vuông 4K nên ghi rõ 4096x4096.

04 Sửa ảnh / vẽ lại cục bộ: multipart

Dùng multipart/form-data cho ảnh tham chiếu và vẽ lại. Không gắn ảnh tham chiếu vào endpoint tạo ảnh từ văn bản.

curl --fail-with-body --max-time 600 "https://kuaiapi.net/v1/images/edits" \
  -H "Authorization: Bearer $KUAiapi_API_KEY" \
  --form-string 'model=gpt-image-2.5-flare' \
  --form-string 'prompt=Giữ chủ thể, đổi nền sang xanh nhạt' \
  -F 'image=@reference.png' \
  --form-string 'size=2048x2048' \
  --form-string 'quality=medium' \
  --form-string 'n=1' \
  --form-string 'response_format=url'

• Một ảnh tham chiếu: image; nhiều ảnh: lặp image[], tối đa 20 MB mỗi file.
• Vẽ lại cục bộ: thêm file mask; vùng trong suốt được vẽ lại, vùng đục được giữ.
• Cả hai nhóm hỗ trợ endpoint này; nhóm upscale dùng nó để phóng to/vẽ lại theo ảnh tham chiếu.

05 Đọc phản hồi

{
  "created": 1794209291,
  "data": [
    { "url": "https://..." }
  ]
}

• Duyệt data[]; mỗi phần tử là một ảnh. Không quét toàn bộ JSON để tìm URL.
• response_format=url → data[].url; response_format=b64_json → data[].b64_json (nội dung Base64, không phải link).
• URL ảnh là tạm thời (thường khoảng 1 giờ); tải hoặc lưu lại ngay.
• Phản hồi có thể có revised_prompt, height, width; dùng theo phản hồi thực tế.

06 Giá và đầu ra

Nhóm	1K	2K	4K	C2PA
GPT-Image (Native)	0.15/ảnh	0.15/ảnh	0.15/ảnh	Có
GPT-Image-Upscale (Upscale)	0.05/ảnh	0.08/ảnh	0.10/ảnh	Không

• Nhóm native có C2PA content credentials.
• Nhóm upscale là upscale sinh tạo, không có C2PA; 4K 16:9 có thể mở rộng khung hình, bố cục theo ảnh thực tế.
• Đã kiểm tra trên site: gpt-image-2.5-flare 2K tạo ảnh và ảnh tham chiếu đều trả 2048×2048, nhóm upscale tính 0.08; native 1K trả 1024×1024, tính 0.15.

07 Async và timeout

Hiện tại các lệnh ảnh là đồng bộ, tối đa 600 giây mỗi request.

• Timeout nghĩa là chưa có kết quả kịp, không phải job thất bại; không retry đồng thời.
• Nếu sau này mở async, chỉ HTTP 202 kèm task_id mới được coi là đã nhận; truy vấn bằng cùng key và tuân theo Retry-After.
• Không có task ID thì giữ x-request-id, thời gian, model và request body đã che dữ liệu để hỗ trợ.

08 Lỗi thường gặp

Lỗi	Kiểm tra trước	Xử lý
400 / Invalid image size	Bội số của 16; kích thước gốc của ảnh tham chiếu	Dùng kích thước ở trên; dùng multipart cho edits
401 / 403 / 404	Key, nhóm, model, đường dẫn đầy đủ	GET /v1/models; không lặp /v1, không dùng key của site khác
429	Đồng thời, tần suất, số dư, giới hạn key	Lùi theo Retry-After; không retry cùng job đồng thời
502 / 503 / 504	Dung lượng dịch vụ hoặc xác thực	Giữ x-request-id, thời gian, model và request body đã che dữ liệu
images/edits requires multipart/form-data	Content-Type của endpoint edits	Dùng multipart/form-data với trường image
Failed to validate API key	Key và nhóm	Kiểm tra key/nhóm; liên hệ hỗ trợ nếu vẫn lỗi

Hai lỗi phổ biến nhất

1. Không dùng www: www.kuaiapi.net chuyển POST /v1/images/* bằng 301 thành GET và lỗi.
2. Không thêm /v1 lần nữa: https://kuaiapi.net/v1 đã có /v1.