Tikhub Skill

TikHub Skill

TikHub (api.tikhub.io) is a pay-per-request REST API that exposes roughly 1,000 scraping endpoints across TikTok, Douyin, Instagram, YouTube, Twitter/X, Xiaohongshu, Bilibili, Kuaishou, Weibo, Reddit, Threads, LinkedIn, Zhihu, Lemon8 and others. Each endpoint is one HTTP call that returns the platform's raw data; there are no long-running jobs, no actors, no datasets to poll. The tikhub_action tool is a thin, flattened wrapper over the official tikhub Python SDK: every SDK method is addressable by its resource-dot-method id (for example douyin_web.fetch_one_video), and the tool passes your params straight through as the SDK's keyword arguments.

Tool: tikhub_action

Operations

Response

call and fetch_url:

{
  "operation": "call",
  "endpoint": "douyin_web.fetch_one_video",
  "path": "/api/v1/douyin/web/fetch_one_video",
  "data": { "aweme_detail": { "aweme_id": "7372484719365098803", "desc": "...", "statistics": { "digg_count": 12345 } } },
  "code": 200,
  "router": "/api/v1/douyin/web/fetch_one_video",
  "cost_usd": 0.001
}

data is the platform payload exactly as TikHub returns it - the shape differs per endpoint and per platform. code / router are TikHub's own envelope fields. cost_usd is what this call was billed.

list_endpoints:

{
  "operation": "list_endpoints",
  "platform": "twitter",
  "count": 13,
  "total": 13,
  "endpoints": [
    {
      "endpoint": "twitter_web.fetch_search_timeline",
      "resource": "twitter_web",
      "method": "fetch_search_timeline",
      "http_method": "GET",
      "path": "/api/v1/twitter/web/fetch_search_timeline",
      "summary": "Search",
      "params": [
        { "name": "keyword", "type": "str", "required": true },
        { "name": "search_type", "type": "str | None", "required": false },
        { "name": "cursor", "type": "str | None", "required": false }
      ]
    }
  ]
}

count is how many endpoints came back after search + limit; total is how many the platform has. With platform: "all" and no search the listing is capped, so always narrow by platform or search term.

On failure the tool raises an error carrying TikHub's own message - surface it verbatim (see "Errors" below).

The discover-then-call loop

Never guess an endpoint id or its parameter names. Endpoints are introspected from the installed SDK at runtime, so list_endpoints is always exact, free, and returns the required flag for every parameter.

1. Narrow by platform and a search term:

{ "operation": "list_endpoints", "platform": "douyin", "search": "comments" }

2. Read the params list of the endpoint you picked, then call it with exactly those keyword names:

{ "operation": "call", "endpoint": "douyin_web.fetch_video_comments", "params": { "aweme_id": "7372484719365098803", "count": 20 } }

3. Paginate by feeding the cursor that came back in data into the next call (see "Pagination").

The endpoint field also accepts the REST path (/api/v1/douyin/web/fetch_video_comments) or the slash spelling (douyin_web/fetch_video_comments); all three resolve to the same SDK method. An unknown id fails before any network call and the error lists the closest matches.

Unknown keyword names are rejected before the request is sent, and the error lists the accepted parameters - fix the names and retry, do not retry the same call.

POST batch endpoints

A few endpoints take a JSON body instead of query parameters (the SDK signature shows a single body argument). Pass it as the body key inside params:

{ "operation": "call", "endpoint": "douyin_web.fetch_multi_video", "params": { "body": ["7372484719365098803", "7372484719365098804"] } }

Share URLs: prefer fetch_url

For any TikTok or Douyin share link (including short links on v.douyin.com and vm.tiktok.com), use fetch_url first. It resolves the link and returns the full video payload in one billed request without you having to extract an aweme_id:

{ "operation": "fetch_url", "url": "https://www.tiktok.com/@scout2015/video/7372484719365098803" }
{ "operation": "fetch_url", "url": "https://v.douyin.com/iRNBho6u/", "minimal": true }

minimal: true trims the payload to the fields most tasks need (id, description, author, stats, media URLs). For other platforms use the platform's own URL-accepting endpoint (instagram_v3.get_post_info takes a url, kuaishou_web.fetch_one_video_by_url takes a url, xiaohongshu_web.get_note_info_v7 takes share_text).

Per-platform cheat sheet

Ids below are verified against the installed SDK. Parameter names are the SDK keyword names; list_endpoints remains the authority for the full signature.

TikTok

Two resource families: tiktok_web (web-client fields, camelCase params such as secUid / uniqueId / itemId) and tiktok_app_v3 (app-client fields, snake_case params such as sec_user_id / unique_id / aweme_id). Both return TikTok data; the app family tends to carry richer statistics, the web family is lighter.

Douyin

douyin_web is the primary family; douyin_app_v3 mirrors it with app fields; douyin_search holds the current search endpoints (POST, but still plain keyword params).

Instagram

Three generations exist: instagram_v1, instagram_v2, instagram_v3. Prefer instagram_v3 (newest; most endpoints accept either user_id or username). instagram_v2 remains useful for hashtag / location / music feeds and paginates with pagination_token.

YouTube

youtube_web is the primary family; youtube_web_v2 adds captions, stream URLs, community posts and URL-accepting variants.

Twitter / X

Xiaohongshu (RedNote)

Families: xiaohongshu_web (note detail, search, user), xiaohongshu_app_v2 (comments, topic feeds, search variants), plus older xiaohongshu_app, xiaohongshu_web_v2, xiaohongshu_web_v3. Most note endpoints accept either a note_id or the raw share_text copied from the app.

Other platforms

Every other family follows the same shape - run list_endpoints with the platform to see them. Starting points: bilibili_web.fetch_one_video (bv_id), kuaishou_web.fetch_one_video_by_url (url), weibo_web_v2.fetch_post_detail (id), reddit_app.fetch_post_details (post_id), threads_web.fetch_post_detail (post_id), linkedin_web_v2.get_user_profile (username), zhihu_web.fetch_question_answers (question_id).

Hybrid parsing and account

Pagination

Cursor names vary by platform. Read the cursor from data and pass it back under the parameter name the endpoint declares:

Fetch pages sequentially - each page is one billed request, and the same endpoint path is limited to 10 requests per second.

Cost and rate limits

• Roughly $0.001 per successful request (TikHub bills only 2xx responses; failed calls are free). list_endpoints never calls the API and costs nothing.
• 10 requests per second per endpoint path. Bursting past it returns 429; the SDK retries with backoff, and the tool reports retry_after when TikHub sends it.
• Before a large crawl (hundreds of pages), run account and tell the user the balance; tikhub_user.calculate_price gives a projection for one endpoint.
• Every call result carries cost_usd; costs are also recorded in OpenCompany's API usage panel under the tikhub service.

Errors

The tool raises a plain error message; relay it to the user as-is and act on the class of failure:

A 200 whose body says code: 4xx is also raised as an error with TikHub's message - the platform returned nothing useful for that id.

Authentication

OpenCompany stores the TikHub API key encrypted; you never see it and must never ask the user to paste it into the chat. If a call fails with the 401 message, tell the user: open Credentials -> Scrapers -> TikHub, paste the key from the TikHub user portal (tikhub.io -> API Keys) and click Validate - the modal shows the account email and balance when the key is accepted.

Working inside a team

When this node is wired to a teammate rather than directly to the lead, the lead never sees the tikhub_action tool itself. It sees one roster line per teammate that lists the teammate's connected tools and skills, built from this node's description and this skill's description, and it assigns work through task_manager with a bounded mission. As the teammate holding TikHub:

1. Treat the mission as the query: pick the platform from the URL or the wording, run list_endpoints if the endpoint id is not obvious, then call or fetch_url.
2. Return the extracted fields the mission asked for, not the raw TikHub payload. Include the endpoint id used, the count of items, and the total cost_usd so the lead can report spend.
3. If the key is missing or the balance is exhausted, say so in the result verbatim so the lead can escalate to the user; do not retry blindly.

Best practices

1. Prefer fetch_url for any share URL. One request, no id extraction, works for TikTok and Douyin links including short links.
2. Use list_endpoints before guessing. It is free, exact for the installed SDK, and shows which params are required. Pick the highest _vN suffix when several variants exist unless the user needs a specific field set.
3. Pass params by their SDK names, as a JSON object, values typed as the signature says (count is an int, cursors are usually strings).
4. Paginate deliberately. Report how many pages you fetched and stop when has_more (or the platform's equivalent) turns false; do not loop without a page cap the user agreed to.
5. Surface errors verbatim. TikHub's detail strings are precise; do not paraphrase them or retry blindly on 401 / 403 / 404.
6. Keep data intact when relaying to downstream nodes - the raw platform payload is what other nodes and the user's exports expect.
7. Respect the platforms' terms and the user's intent: scrape public content only, do not collect personal data beyond the task, and do not hammer one endpoint past 10 req/s.