Logo Ảnh thành URL

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.

Ảnh sản phẩm

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"
}