HTML sang ảnh

Chụp một URL trang web hoặc nội dung HTML thô thành ảnh chụp màn hình. Hỗ trợ giả lập thiết bị (desktop, tablet, mobile), chụp toàn trang và nhiều định dạng đầu ra.

Điểm cuối API

POST /api/v1/tools/image/html-to-image

Chấp nhận một thân JSON (không phải multipart). Không cần tải lên tệp.

Tham số

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
url	string	Có điều kiện	-	URL cần chụp (phải là một URL hợp lệ)
html	string	Có điều kiện	-	Nội dung HTML thô để kết xuất (1 đến 5.000.000 ký tự)
format	string	Không	"png"	Định dạng đầu ra: jpg, png, webp
quality	number	Không	90	Chất lượng đầu ra cho các định dạng mất dữ liệu (1 đến 100)
fullPage	boolean	Không	false	Chụp toàn bộ trang có thể cuộn, không chỉ khung nhìn
devicePreset	string	Không	"desktop"	Giả lập thiết bị: desktop, tablet, mobile, custom
viewportWidth	number	Không	1280	Chiều rộng khung nhìn tùy chỉnh tính bằng pixel (320 đến 3840, dùng khi devicePreset là custom)
viewportHeight	number	Không	720	Chiều cao khung nhìn tùy chỉnh tính bằng pixel (320 đến 2160, dùng khi devicePreset là custom)

Phải cung cấp url hoặc html, nhưng không phải cả hai.

Cấu hình thiết bị dựng sẵn

Cấu hình	Chiều rộng	Chiều cao	UA di động
desktop	1280	720	Không
tablet	768	1024	Không
mobile	375	812	Có
custom	(người dùng chỉ định)	(người dùng chỉ định)	Không

Ví dụ yêu cầu

Chụp một trang web:

curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "fullPage": true, "devicePreset": "desktop"}'

Kết xuất nội dung HTML:

curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<div style=\"padding: 20px; background: #f0f0f0;\"><h1>Hello</h1></div>", "format": "png"}'

Ví dụ phản hồi

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/screenshot.png",
  "originalSize": 0,
  "processedSize": 145000
}

Ghi chú

• Yêu cầu Chromium được cài đặt trên máy chủ. Trả về HTTP 503 nếu dịch vụ trình duyệt không khả dụng.
• Các URL được kiểm tra chống lại tấn công SSRF (các địa chỉ mạng riêng/nội bộ bị chặn).
• Điểm cuối này bị giới hạn tốc độ ở mức 120 yêu cầu mỗi giờ.
• originalSize luôn là 0 vì công cụ này tạo ảnh từ URL/HTML.
• Tên tệp đầu ra là screenshot.<format>.
• Nếu trang mất quá nhiều thời gian để tải, yêu cầu trả về HTTP 504 (gateway timeout).
• Nếu dịch vụ trình duyệt liên tục gặp sự cố, nó tạm thời bị vô hiệu hóa và trả về HTTP 503 với mã BROWSER_CRASHED.