文档开发者工具SDKsNode.js / TypeScript SDK

Node.js SDK

概述

官方 Scrapeless Node.js SDK 提供对浏览器自动化、抓取、爬取、Proxies、搜索结果以及 AI 聊天内容提取的访问能力。本指南遵循 SDK 仓库 README，并附有可运行的示例和配置详情。

环境要求

使用 Node.js 搭配 npm、pnpm 或 Yarn。包清单 未声明最低 Node.js 版本；仓库的发布工作流使用 Node.js 20。支持 JavaScript 和 TypeScript，并同时提供 ES module 和 CommonJS 导出。

以下示例使用 ES modules。请将它们保存为 .mjs 文件，或在项目的 package.json 中设置 "type": "module"。

安装

npm install @scrapeless-ai/sdk

你也可以使用 pnpm add @scrapeless-ai/sdk 或 yarn add @scrapeless-ai/sdk。

身份验证 / API Key

登录 Scrapeless 控制台 并创建一个 API key。在运行示例之前将其导出：

export SCRAPELESS_API_KEY="YOUR_API_KEY"

请将 API key 保存在环境变量或密钥管理器中，而不要提交到源代码管理系统。

new Scrapeless() 会读取 SCRAPELESS_API_KEY。你也可以在构造客户端时传入 apiKey 选项。

快速开始

将以下内容保存为 quickstart.mjs，在设置好 API key 后运行 node quickstart.mjs。

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless();
const result = await client.universal.scrape({
  actor: 'unlocker.webunlocker',
  input: { url: 'https://example.com', method: 'GET', redirect: false }
});
console.log(result);

产品覆盖矩阵

产品SDK 服务覆盖范围
Agent Browserclient.browser创建和管理远程浏览器会话。
Browser Profilesclient.profiles在多个会话之间持久化浏览器数据。
Scraping APIclient.scraping使用网站 actor 提取结构化数据。
Web Unlockerclient.universal从受保护的网站获取内容。
Crawlclient.scrapingCrawl抓取单个页面或爬取整个网站。
Google Search APIclient.deepserp提取搜索引擎结果。
Proxiesclient.proxies生成代理连接 URL。
AI Scraperclient.aiScraper创建 AI 聊天任务并获取其状态和结果。

使用示例

除非示例自行初始化客户端，否则请复用快速开始中的 const client = new Scrapeless()。

Browser

本示例需要安装 Puppeteer：npm install puppeteer-core。关于 Playwright 以及 SDK 的浏览器封装，请参阅 浏览器集成示例。

高级浏览器会话管理，支持 Playwright 和 Puppeteer 框架，具备可配置的反检测能力（例如指纹伪装、CAPTCHA 求解）以及可扩展的自动化工作流：

import { Scrapeless } from '@scrapeless-ai/sdk';
import puppeteer from 'puppeteer-core';
 
const client = new Scrapeless();
 
// Create a browser session
const { browserWSEndpoint } = await client.browser.create({
  sessionName: 'my-session',
  sessionTTL: 180,
  proxyCountry: 'US'
});
 
// Connect with Puppeteer
const browser = await puppeteer.connect({
  browserWSEndpoint: browserWSEndpoint
});
 
try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
} finally {
  await browser.close();
}

Browser Profile

管理浏览器 profile 以实现持久化会话。

const createResponse = await client.profiles.create('My Profile');
console.log('Profile created:', createResponse);
 
const profiles = await client.profiles.list({ page: 1, pageSize: 10 });
console.log('Profiles:', profiles.docs);
 
const profile = await client.profiles.get(createResponse.profileId);
console.log('Profile details:', profile);
 
// Delete the profile when it is no longer needed.
await client.profiles.delete(createResponse.profileId);

Scraping API

面向网站（例如电商、旅游平台）的直接数据提取 API。通过预构建的连接器获取结构化的产品信息、价格和评论：

const result = await client.scraping.scrape({
  actor: 'scraper.google.search',
  input: {
    'q': 'coffee',
    'hl': 'en',
    'gl': 'us'
  }
});
 
console.log(result.data);

Web Unlocker

使用 Web Unlocker（暴露为 client.universal）从网站提取数据。

const result = await client.universal.scrape({
  actor: 'unlocker.webunlocker',
  input: { url: 'https://example.com', method: 'GET', redirect: false }
});
console.log(result);

Crawl

从单个页面提取数据或遍历整个域名，并以 Markdown、JSON、HTML、截图和链接等多种格式导出。

const result = await client.scrapingCrawl.scrapeUrl('https://example.com');
 
console.log(result);

Proxy

使用你的网关和会话设置生成代理 URL。

const proxyUrl = client.proxies.proxy({
  type: 'residential',
  country: 'US',
  sessionDuration: 30,
  sessionId: client.proxies.generateSessionId(),
  gateway: 'your-proxy-gateway:port'
});
console.log(proxyUrl);

AI Scraper

创建任务：client.aiScraper.createTask(request)

传入必需的 actor 以及特定于 actor 的 input。可选的 webhook 对象接受一个回调 url。该 promise 会解析为完整的 API 响应，其中包含 task_id 和 status，以及在可用时的 task_result。

批量提取 AI 聊天内容，以监控品牌提及、比较回答，并从最新模型中分析竞争情报。通过一次集成即可获取 URL、prompt、Markdown 回答、引用等内容。

支持的 actor 包括 scraper.chatgpt、scraper.perplexity、scraper.copilot、scraper.gemini、scraper.aimode、scraper.overview、scraper.grok 和 scraper.alexa。input JSON 取决于具体的 actor；详细参数请参阅 AI Scraper 文档。可选的 webhook JSON 包含一个回调 url。

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless(); // Uses SCRAPELESS_API_KEY
 
const task = await client.aiScraper.createTask({
  actor: 'scraper.chatgpt',
  input: {
    prompt: 'Most reliable proxy service for data extraction',
    country: 'US',
    web_search: true
  },
  // Optional: webhook: { url: 'https://your-webhook.example.com' }
});
console.log('Created task:', task);

获取任务状态和结果：client.aiScraper.getTaskResult(taskId)

传入创建任务时返回的 task_id。可以在同一脚本中继续，或存储该 ID 并在后续请求中获取结果。

const result = await client.aiScraper.getTaskResult(task.task_id);
 
switch (result.status) {
  case 'success':
    console.log('Task result:', result.task_result);
    break;
  case 'failed':
    console.error('Task failed:', result.message);
    break;
  case 'running':
    console.log('Task is running. Retrieve the result again later.');
    break;
}

两个方法都会原样返回 API JSON。创建操作返回 task_id、status，以及在可用时返回 task_result。结果获取操作返回 status、在可用时返回 task_result，以及失败时返回 message。状态为 success、failed 或 running；SDK 不会自动轮询。

状态含义后续步骤
running任务仍在处理中。稍后再次调用 getTaskResult，或使用 webhook。
success任务已完成。读取 task_result；其结构取决于具体的 actor。
failed任务无法完成。读取 message 以了解失败原因。

创建操作可能已经包含结果。在安排进一步请求之前请先检查其状态。如果你实现轮询，请使用延迟和整体超时。

Google Search API

const result = await client.deepserp.scrape({
  actor: 'scraper.google.search',
  input: { q: 'nike site:www.nike.com' }
});
console.log(result);

有关更完整的集成，请浏览仓库的 examples 目录。

错误处理

捕获 ScrapelessError 以处理 API 请求失败。请单独检查 AI Scraper 响应的 status：任务可能返回 failed，而 HTTP 请求本身并不抛出错误。

import { Scrapeless, ScrapelessError } from '@scrapeless-ai/sdk';
 
try {
  const client = new Scrapeless();
  const result = await client.universal.scrape({
    actor: 'unlocker.webunlocker',
    input: { url: 'https://example.com', method: 'GET' }
  });
  console.log(result);
} catch (error) {
  if (error instanceof ScrapelessError) {
    console.error('Scrapeless error:', error.message);
    console.error('Status code:', error.statusCode);
  } else {
    throw error;
  }
}

配置 / 环境变量

API key 是必需的。端点覆盖是可选的；下表展示了它们的默认值。

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless({
  apiKey: process.env.SCRAPELESS_API_KEY,
  timeout: 30000, // Request timeout in milliseconds
  baseApiUrl: 'https://api.scrapeless.com',
  browserApiUrl: 'https://browser.scrapeless.com',
  scrapingCrawlApiUrl: 'https://api.scrapeless.com'
});

显式配置优先于环境变量。默认请求超时为 30,000 毫秒。

环境变量用途 / 默认值
SCRAPELESS_API_KEY来自控制台的必需 API key。
SCRAPELESS_BASE_API_URLhttps://api.scrapeless.com
SCRAPELESS_BROWSER_API_URLhttps://browser.scrapeless.com
SCRAPELESS_CRAWL_API_URLhttps://api.scrapeless.com

支持

该 SDK 基于 MIT License 发布。

相关项目

SDK 概览Python SDK