WebsiteScreenshotWebsiteScreenshotOnline

API 文档

欢迎使用 WebsiteScreenshot API 文档。我们的 API 允许您通过编程方式抓取任何网站的高质量截图和视频。

基础 URL

Http
https://websitescreenshot.online/api/v1

身份验证

所有 API 请求都需要使用 API 密钥进行身份验证。请在 Authorization 请求头中包含您的 API 密钥：

Http
Authorization: Bearer YOUR_API_KEY

获取 API 密钥

  1. 在 websitescreenshot.online 注册账户
  2. 导航至 控制面板 (Dashboard)
  3. 根据您的需求创建新的 API 密钥
  4. 复制 API 密钥（如果启用了签名验证，还需复制 Secret 密钥）

频率限制

  • 截图 API: 每分钟 10 次请求
  • 视频 API: 每分钟 5 次请求
  • 通用 API: 每 15 分钟 100 次请求

所有响应中都包含频率限制相关的响应头：

  • X-RateLimit-Limit: 允许的最大请求数
  • X-RateLimit-Remaining: 当前窗口剩余的请求数
  • X-RateLimit-Reset: 频率限制重置的 Unix 时间戳

截图 API

POST /api/v1/screenshot

抓取任何网站的截图。

请求参数

参数类型必填说明
url
string
是
要抓取的 URL（必须包含 http:// 或 https://）
resolution
object
否
视口尺寸对象，包含 width 和 height 属性
resolution.width
integer
否
视口宽度（像素）
resolution.height
integer
否
视口高度（像素）
fullSize
boolean
否
抓取全屏高度（默认：false），如果为 true，则忽略 resolution 中的高度
format
string
否
输出格式：png, jpeg, pdf（默认：png）
blockCookiesGdpr
boolean
否
屏蔽 Cookie 同意弹窗（默认：true）
blockAds
boolean
否
屏蔽广告（默认：true）
delay
integer
否
抓取前的等待时间（秒，默认：1，最大：10）

请求示例

JavaScript (Node.js)
Javascript
const axios = require('axios');

async function captureScreenshot() {
  try {
    const response = await axios.post('https://websitescreenshot.online/api/v1/screenshot', {
      url: 'https://example.com',
      resolution: {
        width: 1920,
        height: 1080
      },
      format: 'png',
      fullSize: true,
      blockCookiesGdpr: true,
      blockAds: true,
      delay: 3
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log('截图 URL:', response.data.url);
    console.log('文件大小:', response.data.size);
  } catch (error) {
    console.error('错误:', error.response?.data || error.message);
  }
}

captureScreenshot();
JavaScript (Fetch)
Javascript
async function captureScreenshot() {
  try {
    const response = await fetch('https://websitescreenshot.online/api/v1/screenshot', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        url: 'https://example.com',
        resolution: {
          width: 1920,
          height: 1080
        },
        format: 'png',
        fullSize: true,
        blockCookiesGdpr: true,
        blockAds: true,
        delay: 2
      })
    });
    
    const data = await response.json();
    
    if (response.ok) {
      console.log('截图 URL:', data.url);
      console.log('文件大小:', data.size);
    } else {
      console.error('错误:', data.error);
    }
  } catch (error) {
    console.error('网络错误:', error);
  }
}

captureScreenshot();
Python
Python
import requests
import json

def capture_screenshot():
    url = "https://websitescreenshot.online/api/v1/screenshot"
    
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    data = {
        "url": "https://example.com",
        "resolution": {
            "width": 1920,
            "height": 1080
        },
        "format": "png",
        "fullSize": True,
        "blockCookiesGdpr": True,
        "blockAds": True,
        "delay": 2
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        
        result = response.json()
        print(f"截图 URL: {result['url']}")
        print(f"文件大小: {result['size']}")
        
    except requests.exceptions.RequestException as e:
        print(f"错误: {e}")
        if hasattr(e.response, 'json'):
            print(f"详情: {e.response.json()}")

capture_screenshot()
cURL
Bash
curl -X POST https://websitescreenshot.online/api/v1/screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "resolution": {"width": 1920, "height": 1080},
    "format": "png",
    "fullSize": true,
    "blockCookiesGdpr": true,
    "blockAds": true,
    "delay": 2
  }'

响应

Json
{
  "success": true,
  "imageUrl": "https://websitescreenshot.online/screenshots/example-com-2024-01-15-123456.png",
  "filename": "example-com-2024-01-15-123456.png"
}

视频录制 API

POST /api/v1/video

录制网站交互视频。

请求参数

参数类型必填说明
url
string
是
要录制的 URL
resolution
object
否
视口尺寸对象，包含 width 和 height 属性
resolution.width
integer
否
视口宽度（像素）
resolution.height
integer
否
视口高度（像素）
format
string
否
输出格式：webm, mp4（默认：webm）
scrollDistance
integer
否
每次滚动的距离（仅限 step 模式，像素。默认：500，最小：100，最大：1000）
scrollDelay
integer
否
滚动之间的延迟（仅限 step 模式，毫秒。默认：1000，最小：200，最大：5000）
scrollMode
string
否
滚动模式：step（步进滚动）, smooth（平滑滚动）（默认：step）
smoothScrollSpeed
string
否
平滑滚动速度：slow, normal, fast（默认：normal，仅在 scrollMode 为 smooth 时有效）
blockCookiesGdpr
boolean
否
屏蔽 Cookie 同意弹窗（默认：true）
blockAds
boolean
否
屏蔽广告（默认：true）
delay
integer
否
录制前的等待时间（秒，默认：1，最大：10）
async
boolean
否
是否异步处理请求（默认：false）。如果为 true，则立即返回 requestId。

请求示例

Javascript
const response = await fetch('https://websitescreenshot.online/api/v1/video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    resolution: {
      width: 1920,
      height: 1080
    },
    format: 'mp4',
    scrollMode: 'smooth',
    smoothScrollSpeed: 'normal',
    blockCookiesGdpr: true,
    blockAds: true,
    delay: 1
  })
});

const data = await response.json();
console.log('视频 URL:', data.videoUrl);

响应

Json
{
  "success": true,
  "videoUrl": "https://websitescreenshot.online/videos/example-com-2024-01-15-123456.webm",
  "filename": "example-com-2024-01-15-123456.webm",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

GET /api/v1/video/status

检查异步视频录制请求的状态。

查询参数

参数类型必填说明
requestId
string
是
初始 POST 请求返回的 ID

响应

Json
{
  "status": "completed",
  "result": {
    "success": true,
    "videoUrl": "https://websitescreenshot.online/videos/example-com-...webm",
    "filename": "example-com-...",
    "requestId": "..."
  },
  "updatedAt": 1711377251000
}

可能的 status 值：pending（进行中）, completed（已完成）, error（错误）。 结果通常保留 24 小时。

请求签名（增强安全性）

为了增强安全性，您可以为 API 密钥启用请求签名。这可以防止重播攻击并确保请求完整性。

启用请求签名

  1. 创建 API 密钥时，勾选 "Require Request Signatures" (需要请求签名)
  2. 保存 API 密钥和 Secret 密钥
  3. 在请求中包含签名相关的请求头

必需的请求头

  • X-Timestamp: 当前 Unix 时间戳（毫秒）
  • X-Nonce: 随机字符串（建议 16 位以上）
  • X-Signature: HMAC-SHA256 签名

签名生成

签名是使用 HMAC-SHA256 对以下负载生成的：

Text
METHOD|URL|TIMESTAMP|NONCE

JavaScript 示例

Javascript
const crypto = require('crypto');

function generateSignature(method, url, timestamp, nonce, secretKey) {
  const payload = `${method}|${url}|${timestamp}|${nonce}`;
  return crypto.createHmac('sha256', secretKey).update(payload).digest('hex');
}

错误响应

所有错误都遵循一致的格式：

Json
{
  "code": "ERROR_CODE",
  "error": "错误消息"
}

常见错误代码

代码状态码说明
HTTPS_REQUIRED
400
需要 HTTPS。生产环境中的 API 请求必须使用 HTTPS。
INVALID_URL
400
提供的 URL 无效或无法访问
SIGNATURE_INVALID
400
请求签名验证失败
TIMEOUT
400
请求超时
DNS_RESOLUTION
400
DNS 解析失败
CONNECTION_REFUSED
400
连接被拒绝
SSL_CERTIFICATE
400
SSL 证书错误
PAGE_NOT_FOUND
400
页面未找到
INVALID_PARAMETERS
400
一个或多个参数无效
UNAUTHORIZED
401
API 密钥无效或缺失
FORBIDDEN
403
IP 地址不在白名单中
RATE_LIMITED
429
已达到频率限制
USAGE_LIMIT_EXCEEDED
429
已达到使用限制
INTERNAL_ERROR
500
内部服务器错误

最佳实践

1. 处理频率限制

始终检查频率限制相关的响应头，并实现指数退避：

Javascript
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = Math.max(1000, (resetTime * 1000) - Date.now());
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  
  throw new Error('已超过最大重试次数');
}

支持