API Manual

Polymer-spider API 文档

Polymer-spider 是一个面向短视频与社媒数据的统一网关。当前版本已经接入 JustOneAPI 上游，并提供 TikTok、YouTube Shorts、小红书、抖音相关的数据检索、详情、评论、用量统计和后台管理接口。

Base URL https://polymer-spider.pages.dev/api/v1

Quick Start

最快接入方式

先在 Dashboard 的 API 令牌页面生成一个 ps_live_... 密钥，然后在请求头里传入 Authorization: Bearer YOUR_API_KEY。所有 Customer API 都返回 JSON。

curl -X POST "https://polymer-spider.pages.dev/api/v1/search" \
  -H "Authorization: Bearer ps_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "coffee",
    "platforms": ["xiaohongshu", "douyin"],
    "limit": 10
  }'

Authentication

Polymer-spider 有两类鉴权：对外售卖的数据 API 使用 API Key；工作台管理接口使用登录后返回的 Dashboard Session Token。两者都通过 Bearer Token 传递。

Customer APIBearer API Key用于 /search、/videos、/comments、/usage 等对外接口。

Dashboard APIBearer Session用于 /dashboard/* 管理余额、令牌、任务和调用记录。

Authorization: Bearer ps_live_your_key
Content-Type: application/json

Billing Model

已接入 D1 余额系统。新用户默认只有 5 次免费 API 调用机会；试用次数用完后，成功调用可计费接口时，系统会按照定价表扣减客户余额，并写入 api_call_logs 与 ledger_entries。余额不足会返回 402 insufficient_balance。

/api/v1/search¥0.0100每次关键词搜索。

/api/v1/videos/{platform}/{id}¥0.0060单条视频详情。

/api/v1/notes/xiaohongshu/{id}¥0.0060小红书笔记详情。

/api/v1/comments¥0.0080评论列表。

/api/v1/channels/youtube/{id}¥0.0120YouTube 频道视频列表。

Customer API

对外数据接口

这一组接口是可以包装成你自己产品向客户售卖的核心能力。

GET

Status API

/status

公开状态检查接口，不需要 API Key。用于检测网关版本、上游配置和当前可用 endpoint。

curl "https://polymer-spider.pages.dev/api/v1/status"

GET

Health API

/health

带鉴权的服务健康检查。适合客户侧后台在保存 API Key 后做连通性测试。

curl "https://polymer-spider.pages.dev/api/v1/health" \
  -H "Authorization: Bearer ps_live_your_key"

GET

Platforms API

/platforms

返回当前支持的平台、别名、接入状态和可用能力。

Response Shape

{
  "code": 0,
  "data": [
    {
      "id": "xiaohongshu",
      "name": "Xiaohongshu",
      "status": "ready",
      "features": ["search", "note_details", "comments"]
    }
  ]
}

POST

Search API

/search

按关键词跨平台搜索内容。当前真实上游支持小红书和抖音搜索；TikTok、YouTube 在搜索里会被标记为 unsupported_platforms，但它们的视频详情接口可用。

keywordstring required搜索关键词，也支持 query。

platformsstring[]xiaohongshu、douyin。GET 调用可用 platforms=xiaohongshu,douyin。

limitnumber返回数量，建议 1 到 50。

start / enddatetime可选，JustOneAPI 格式，例如 2026-05-01 00:00:00。

cursorstring分页游标。

POST Example

/api/v1/videos/search 是同一个搜索接口的兼容别名。

curl -X POST "https://polymer-spider.pages.dev/api/v1/search" \
  -H "Authorization: Bearer ps_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "出海营销",
    "platforms": ["xiaohongshu", "douyin"],
    "limit": 20,
    "start": "2026-05-01 00:00:00",
    "end": "2026-05-19 23:59:59"
  }'

GET

Video Detail API

/videos/{platform}/{id}

获取单条视频详情。支持 douyin、tiktok、youtube。

curl "https://polymer-spider.pages.dev/api/v1/videos/tiktok/POST_ID" \
  -H "Authorization: Bearer ps_live_your_key"

GET

Xiaohongshu Note API

/notes/xiaohongshu/{id}

获取小红书笔记详情，返回正文、作者、媒体、互动指标和上游原始数据字段。

curl "https://polymer-spider.pages.dev/api/v1/notes/xiaohongshu/NOTE_ID" \
  -H "Authorization: Bearer ps_live_your_key"

GET

Comments API

/comments

获取小红书笔记评论。当前 platform 默认是 xiaohongshu。

platformstring当前支持 xiaohongshu。

item_idstring required笔记 ID，也支持 note_id。

curl "https://polymer-spider.pages.dev/api/v1/comments?platform=xiaohongshu&item_id=NOTE_ID" \
  -H "Authorization: Bearer ps_live_your_key"

GET

YouTube Channel Videos API

/channels/youtube/{id}

获取 YouTube 频道视频列表。分页时传入上一次返回的 cursor。

curl "https://polymer-spider.pages.dev/api/v1/channels/youtube/CHANNEL_ID?cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer ps_live_your_key"

GET

Usage API

/usage

查询当前 API Key 对应客户近 30 天调用量、成功次数、上游错误和人民币消费。

curl "https://polymer-spider.pages.dev/api/v1/usage" \
  -H "Authorization: Bearer ps_live_your_key"

Dashboard API

工作台管理接口

Dashboard API 给主站工作台使用。它们操作客户余额、API Key、任务、价格表和调用记录。请求头使用登录接口返回的 Session Token。

POST

Login API

/auth/login

后台登录，成功后返回 Dashboard Session Token。

curl -X POST "https://polymer-spider.pages.dev/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@polymer-spider.ai",
    "password": "your_password"
  }'

GET

Session API

/auth/session

校验当前 Dashboard Session 是否有效，并返回用户邮箱、角色和过期时间。

GET

Dashboard Summary API

/dashboard/summary

工作台首页聚合数据：客户余额、API Key、平台能力、定价、账单流水、调用日志和任务列表。

POST

API Keys API

/dashboard/api-keys

管理客户可对外使用的 ps_live_... API Key。

Create / Revoke

GET 返回密钥列表；POST 创建新密钥；POST + action=revoke 吊销密钥。

# create
curl -X POST "https://polymer-spider.pages.dev/api/v1/dashboard/api-keys" \
  -H "Authorization: Bearer DASHBOARD_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production key"}'

# revoke
curl -X POST "https://polymer-spider.pages.dev/api/v1/dashboard/api-keys" \
  -H "Authorization: Bearer DASHBOARD_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"revoke","id":"key_xxx"}'

POST

Balance API

/dashboard/balance

GET 查询余额和流水；POST 固定充值包、自定义充值金额或手动扣费。当前适合个人开发者先走人工收款、后台加余额模式。

curl -X POST "https://polymer-spider.pages.dev/api/v1/dashboard/balance" \
  -H "Authorization: Bearer DASHBOARD_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "recharge",
    "amount_cny": 100,
    "note": "Manual recharge"
  }'

POST

Tasks API

/dashboard/tasks

创建一次后台搜索任务并保存任务状态。GET 返回最近任务列表。

curl -X POST "https://polymer-spider.pages.dev/api/v1/dashboard/tasks" \
  -H "Authorization: Bearer DASHBOARD_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "AI 视频",
    "platforms": ["xiaohongshu"],
    "limit": 10
  }'

GET

Pricing API

/dashboard/pricing

返回当前 D1 定价表，用于工作台定价页展示。

Python Example

不需要专门 SDK 也能接入。下面是最小 Python 调用方式。

import requests

BASE_URL = "https://polymer-spider.pages.dev/api/v1"
API_KEY = "ps_live_your_key"

response = requests.post(
    f"{BASE_URL}/search",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "keyword": "coffee",
        "platforms": ["xiaohongshu", "douyin"],
        "limit": 10,
    },
    timeout=30,
)

print(response.json())

Error Codes

400 bad_request 请求参数缺失或格式不正确。 401 unauthorized API Key 无效或缺失。 401 invalid_session Dashboard Session 无效或过期。 402 insufficient_balance 账户余额不足，无法继续扣费调用。 405 method_not_allowed 请求方法不匹配。 502 upstream_error JustOneAPI 上游请求失败。 503 upstream_not_configured 上游 Token 未配置或服务暂不可用。