SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-chuhaijiang-tiktok-ads

linkfox-chuhaijiang-tiktok-ads

Data & analytics

View repository

Updated 10-16 00:00

About this skill

TikTok Ad & Creative Intelligence

Use this skill to discover public TikTok ads and creative assets, inspect one result, connect an ad to promoted products, or analyze a creative's content structure.

Core Concepts

  • This is public-market intelligence, not the user's private TikTok Ads account or campaign manager.
  • All five endpoints require a lowercase marketplace code: br,de,es,fr,gb,id,it,jp,mx,my,ph,sg,th,us,vn.
  • Search and related-product endpoints return at most 10 records per page.
  • Use the top-level item id returned by ad search with ad detail/related-products, and the id returned by creative search with creative detail. Do not substitute video_id, product_id, or advertiser_id.
  • Ad detail accepts optional include=core. Creative detail accepts include=analysis, include=embedding, or both as a comma-separated string.
  • Monetary metrics are commonly objects such as { "unit": "US", "value": 31 }. Preserve both fields and inspect runtime types before calculating.
  • Each endpoint is billed independently. Do not make an unrequested detail or relationship call after search, and do not repeat a failed/empty search with altered filters without user approval.

Data Fields

Path or field Meaning
data.total_count Total records matched by the endpoint
data.items Primary ad, creative, or related-product records
data.core.items Optional ad performance metrics requested with include=core
data.analysis.items Optional creative hook/formula/angle, transcript, and storyboard analysis
data.embedding.items Optional extracted content, matched tags, and embedding vector
id Endpoint lookup ID for the matching detail/relationship calls
ad_title, advertiser_name, ad_url, web_url Ad identity and public links
video_play_count, video_like_count, video_engagement_rate Creative reach and engagement
total_gmv, video_30d_gmv, video_total_gmv Returned commerce metrics; usually unit/value objects
product_id, product_name / product_title Promoted product identity and title

Read references/api.md before calling. It contains the complete camelCase request fields and production-validated response paths for each endpoint.

Endpoints

Intent Endpoint Script Points/call
Filter and discover ads /chuhaijiang/ad-creative/ads/search chuhaijiang_ad_search.py 18
Inspect one ad /chuhaijiang/ad-creative/ads/detail chuhaijiang_ad_detail.py 9
Find products promoted by an ad /chuhaijiang/ad-creative/ads/related-products chuhaijiang_ad_related_products.py 18
Filter and discover creative assets /chuhaijiang/ad-creative/creatives/search chuhaijiang_creative_search.py 18
Inspect and analyze one creative /chuhaijiang/ad-creative/creatives/detail chuhaijiang_creative_detail.py 9

Call only the endpoint required by the user's current question. Search first only when the user has not already supplied a valid entity ID.

Parameter Guide

  • country: required lowercase marketplace code.
  • page: optional, starts at 1. pageSize: optional, maximum 10 on search and related-products.
  • Ad search supports keyword, category, adType, excludeSparkAds, view/GMV/day ranges, and sort (field:asc or field:desc).
  • Ad detail requires id; request include=core only when performance metrics are needed.
  • Related products requires the ad id and supports pagination.
  • Creative search supports keyword, category, hasProduct, isSponsored, isAigc, and sort.
  • Creative detail requires the creative id. Use analysis for content-structure fields and embedding only when extracted content, tags, or vector data are needed.
  • Use camelCase request names shown in references/api.md; do not send upstream snake_case names.

How to call

  • API endpoint: All 5 LinkFox gateway capabilities use POST; for the full request URL, parameters, responses, and error codes, see references/api.md。
  • Python script：python scripts/<entry>.py '<JSON 参数>' [--inline]
  • Cost constraints: The business entry script by default caches only successful responses for 24 hours; business-successful empty results can also be cached; the cache is isolated by the current working directory, calling identity, gateway, endpoint, and complete request parameters. When the same combination hits, output Cache hit, and no new paid request will be made. HTTP or business failures are not cached;--inline does not bypass the cache;--no-cache forces a real request and may consume compute again, so use it only when the user explicitly agrees to additional consumption or during debugging.

Output strategy (default script behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-chuhaijiang-tiktok-ads-<timestamp>.json（<cwd> is the working directory when the script runs;<session> is taken from the environment variable SESSION_ID, automatically aggregated by user task;writing to /tmp is prohibited, and if the current directory is not writable, report an error)
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts, main business list length, and the first 3 samples; prioritize data.items / business *.items, skip embedding/vector)
  • Add --inline to force full printing to stdout (also written to disk)

Data reading suggestions: First look at the summary to judge whether it is sufficient; when specific fields are needed, prioritize using jq or ConvertFrom-Json to extract on demand from the saved JSON file, avoiding putting the entire JSON into the context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

  • LINKFOX_AGENT_API_KEY and LINKFOXAGENT_API_KEY are both not configured.
  • The gateway returns 401 or 402.
  • The response indicates issues with compute, balance, quota, plan expiration, or recharge.

Usage Examples

python scripts/chuhaijiang_ad_search.py '{"country":"us","keyword":"beauty","page":1,"pageSize":3}'
python scripts/chuhaijiang_ad_detail.py '{"country":"us","id":"7658119807128046879","include":"core"}'
python scripts/chuhaijiang_ad_related_products.py '{"country":"us","id":"7658119807128046879","page":1,"pageSize":3}'
python scripts/chuhaijiang_creative_search.py '{"country":"us","hasProduct":true,"page":1,"pageSize":3}'
python scripts/chuhaijiang_creative_detail.py '{"country":"us","id":"7668708053428047118","include":"analysis,embedding"}'

The IDs above were valid during release validation but may age. In user workflows, prefer IDs from the current search response.

Display Rules

  1. State the marketplace, filters, current page, and data.total_count for searches.
  2. For ads, show title, advertiser, public links, duration, active-day count, views/engagement, GMV/ROAS, product title, and the lookup id when available.
  3. For related products, show product title/images, price range, rating, commission, total and 30-day sales/GMV, status, and product ID.
  4. For creatives, show description, author, launch date, duration, views/likes/comments/shares/saves, engagement, product relationship, GMV/GPM, AIGC flag, and lookup id when available.
  5. When analysis is requested, summarize the hook, formula, angle, structured transcript, and storyboards; do not dump a raw embedding vector into chat.
  6. Preserve returned units, public URLs, identifiers, booleans, nulls, and unknown fields. Never expose API keys or cache-key fingerprints.

Important Limitations

  1. Data describes public market ads and creative assets; it is not private spend, attribution, audience, pixel, campaign, or account data.
  2. This skill cannot create, edit, launch, pause, or optimize ad campaigns and cannot change budgets or bids.
  3. adType and category values are upstream classifications; do not invent enum labels when the user has not supplied a known value.
  4. Results and performance metrics change over time. Report the request date and filters with any analysis.
  5. Embeddings are machine-oriented vectors. Retrieve them only for an explicit downstream similarity/ML need.

User Expression & Scenario Quick Reference

Applicable:

  • Ad discovery and product relationships: "Use Chuhaijiang to find US TikTok beauty ads", "Look at this ad's details and its related products".
  • Creative filtering: "Filter TikTok shoppable materials", "Find AIGC creatives", "Look at sponsored content materials".
  • Structure breakdown: "Use Chuhaijiang to break down this creative's hook, script, and storyboard", "Get material tags or embeddings for similarity analysis".

Adjacent: TikTok product research belongs to linkfox-chuhaijiang-tiktok-product; public video search/detail without an ad-creative requirement belongs to linkfox-chuhaijiang-tiktok-video or linkfox-kalodata-tiktok-video; campaign/account operations belong to a TikTok Ads management integration.

Not applicable: campaign creation, budget/bid changes, audience targeting, pixel/events setup, private-account reporting, media downloading, or image/video generation.

Compute consumption rules

Billing is per endpoint: ad details and creative details cost 9 compute units per call; ad search, ad-related products, and creative search cost 18 compute units per call.

Users pay fees due to compute consumption. Before high-frequency calls or multi-endpoint drilling, first explain the estimated number of calls and compute consumption.

Feedback: Use the Feedback API in references/api.md only when the user explicitly asks to submit feedback or explicitly authorizes submission after an issue is identified. Summarize and sanitize the content; never include API keys, raw user messages, or unrelated task context.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.