Tài liệu API
Truy cập API cần gói Pro hoặc Premium đang hoạt động. Xác thực bằng khóa API rồi tải ảnh vào cùng thư viện như trong Bảng điều khiển. Hạn mức khớp gói trả phí trên website.
Tải ảnh lên
POST /api/v1/upload với multipart/form-data.
Tham số
Authorization- Bắt buộc. Header yêu cầu. Định dạng: Bearer API_KEY_CỦA_BẠN.
file- Bắt buộc. File nhị phân hoặc dữ liệu base64.
name- Tùy chọn. Tên file; tự nhận khi tải file cục bộ bằng multipart.
Ví dụ yêu cầu
File nhị phân
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=@./product.jpg"
Base64
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" \ -F "name=pixel.gif"
Tải file cục bộ luôn dùng POST. Không hỗ trợ GET.
Trường phản hồi
id- Id tài nguyên trong thư viện của bạn.
url- URL CDN dùng trên trang sản phẩm.
fileName- Tên file gốc.
fileSize- Kích thước file (byte).
mimeType- Kiểu MIME của file đã tải lên.
createdAt- Thời gian tải theo UTC, định dạng YYYY-MM-DD HH:mm:ss.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileName": "product.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}Liệt kê ảnh
GET /api/v1/images với page và pageSize tùy chọn (tối đa 100).
curl "https://phototourl.com/api/v1/images?page=1&pageSize=20" \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
Trường phản hồi
resources- Mảng ảnh: id, fileName, url, fileSize, mimeType, createdAt.
page- Số trang hiện tại.
pageSize- Số mục mỗi trang.
total- Tổng số ảnh trong thư viện.
{
"resources": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"fileName": "product.jpg",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}
],
"page": 1,
"pageSize": 20,
"total": 1
}Xóa ảnh
DELETE /api/v1/images/:id. Xóa tệp khỏi lưu trữ và thư viện của bạn.
curl -X DELETE https://phototourl.com/api/v1/images/RESOURCE_ID \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
Trường phản hồi
success- true khi ảnh đã bị xóa.
{ "success": true }Hạn mức
API không có trên Free. Pro và Premium dùng hạn mức tải, lưu trữ và kích thước tệp của gói. Khi vượt hạn mức, API trả lỗi kèm upgradeUrl.
Lỗi
Yêu cầu thất bại trả mã lỗi. Lỗi hạn mức có thể kèm upgradeUrl.
dailyLimitReached— Đã đạt hạn mức tải ngày (HTTP 429).storageLimitReached— Vượt hạn mức lưu trữ (HTTP 413).fileTooLarge— Tệp lớn hơn mức gói cho phép (HTTP 400).401— Khóa API thiếu, không hợp lệ hoặc đã thu hồi.
{
"error": "dailyLimitReached",
"errorParams": { "limit": 1000 },
"plan": "paid",
"limit": 1000,
"upgradeUrl": "https://www.phototourl.com/pricing"
}