douyin-video-search

Files (2)

• SKILL.md
• search-videos.py · scripts/

SKILL.md (first lines)

# Douyin — Video Search

> Keyword → paginated list of videos with author, stats, cover, description, hashtags, download URL

## Language

All process output to user (progress updates, process notifications) follows the user's language.

## Objective

Fetch Douyin video search results for a given keyword, with optional sort order and date filters, returning complete structured data for each video.

## Prerequisites

- Browser is open and navigated to any Douyin page (douyin.com) with an active logged-in session
- User is logged in to Douyin (avatar visible in top-right corner)

## Pre-execution Checks

### 1. Tool Readiness

If browser-act has been confirmed available in the current session → skip this step.

Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

### 2. Login Verification

If login status for Douyin has been confirmed in the current session → skip this step.

Otherwise: navigate to `https://www.douyin.com` and check the top-right corner:
- User avatar or account name visible → logged in, continue
- "登录" button visible → not logged in; inform the user and assist them in completing login via `remote-assist`

User refuses or cannot log in → terminate execution.

## Capability Components

> This Skill's operational boundary = what the user can manually do in their browser. It only reads data already visible to the logged-in user, never bypassing authentication or access controls. JS code is in `scripts/` and invoked via `eval "$(python scripts/xxx.py {params})"`. Use the bash tool for execution.

### API: Search videos by keyword

Navigate to the Douyin search page first to establish cookie context, then call the search API directly.

**Step 1 — Navigate to search page:**

```
navigate https://www.douyin.com/search/{keyword}?type=video
wait stable
```

Replace `{keyword}` with the URL-encoded search term (e.g., `AI%E5%88%9B%E4%B8%9A`).

**Step 2 — Fetch search results:**

```bash
eval "$(python scripts/search-videos.py '{keyword}' --offset {offset} --count 20 --sort-type {sort_type} --publish-time {publish_time} --search-id '{search_id}')"
```

Parameters:
- `keyword`: search term (plain text, script handles URL encoding)
- `--offset`: pagination offset; start at `0`, then use `next_offset` from previous response (default: `0`)
- `--count`: results per page (default: `20`, max: `20`)
- `--sort-type`: sort order — `0`=综合排序/comprehensive (default), `1`=最多点赞/most liked, `2`=最新发布/latest
- `--publish-time`: date filter in days — `0`=不限/all time (default), `1`=一天内/1 day, `7`=一周内/7 days, `180`=六个月内/6 months, `365`=一年内/1 year
- `--search-id`: leave empty for first page; use `next_search_id` from previous response for page 2+

Output example:
```json
{
  "items": [
    {
      "aweme_id": "7656392146064639419",
      "title": "深度还原7姐妹创业 #ai #搞笑视频 #热门",
      "author_name": "楠楠AI小剧场",
      "author_profile_url": "https://www.douyin.com/user/MS4wLjABAAAAY4eph...",
      "video_url": "https://www.douyin.com/video/7656392146064639419",
      "cover_url": "https://p3-pc-sign.douyinpic.com/image-cut-tos-priv/...",
      "description": "深度还原7姐妹创业 #ai #搞笑视频 #热门 #逆天 #宝妈创业",
      "hashtags": ["#ai", "#搞笑视频", "#热门", "#逆天", "#宝妈创业"],
      "download_url": "https://www.douyin.com/aweme/v1/play/?video_id=v2700f...",
      "digg_count": 188184,
      "comment_count": 3346,
      "publish_time": 1782642711
    }
  ],
  "count": 20,
  "has_more": 1,
  "next_offset": 20,
  "next_search_id": "20260709115250C6DC5EE42A6DC2D6B48D"
}
```

**Error handling:**
- `status_code: 2483` → session cookie is invalid or expired; re-verify login and retry navigation step before calling again
- `error: true` in output → check `message` field; most common cause is session expiry, retry after navigating to `https://www.douyin.com` once
- If `count` in response is 0 with `has_more: 0` → no more results, pagination complete

## Enum Parameters

[AI] `sort_type` — UI filter panel options (read from 筛选 dropdown):
- `0`: 综合排序 (comprehensive, default)
- `1`: 最多点赞 (most liked)
- `2`: 最新发布 (latest/newest)

[AI] `publish_time` — UI filter panel options (read from 筛选 dropdown):
- `0`: 不限 (all time, default)
- `1`: 一天内 (within 1 day)
- `7`: 一周内 (within 7 days)
- `180`: 六个月内 (within 6 months)
- `365`: 一年内 (within 1 year)

## Pagination

**API Pagination**: parameter `offset`, type: page-number-style increment. Start value: `0`. Next page: use `next_offset` from response. Also pass `next_search_id` from first response as `--search-id` for all subsequent pages. Termination: `has_more == 0` or `count == 0` in response.

## Success Criteria

`count >= 1` AND `items[0].aweme_id` is non-null AND `items[0].digg_count` is non-null

From browser-act/skills, MIT.

More from browser-act/skills