> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok 广告 API

> 以 JSON 分析 TikTok 上的竞品广告：在 TikTok 广告资料库中搜索广告主在欧洲、英国、瑞士、土耳其和巴西投放的广告，附带展示次数和定向，并从 Creative Center 读取各国的热门广告。

通过异步 task API 以 JSON 读取 TikTok 的广告来源。ADS 是独立的引擎：向 `taskType` `ADS` 发送两个平台之一，并用 `action` 选择要读取的内容。要在各广告资料库之间选择，参见 [广告资料库对比](https://docs.querying.ai/zh/engines/ad-libraries.md)。

* `tiktok_ad_library` 读取 TikTok 广告资料库（Commercial Content Library）。它列出在 34 个地区展示的广告：欧盟和欧洲经济区国家、英国、瑞士、土耳其和巴西。每条广告带有首次和最后展示的日期以及展示次数范围，`ad` 另外提供落地页、付费方、定向，以及按国家、年龄、性别划分的展示次数。用它查看竞品的全部广告。
* `tiktok_creative_center` 读取 TikTok Creative Center 的热门广告。它列出 28 个国家（包括美国、韩国和日本）在最近 7、30 或 180 天表现最好的广告，附带点击率、点赞数和行业。用它了解哪些素材在某个市场有效。

两个平台的搜索都按返回的**每 30 条广告收取 0.5 积分**。`advertisers` 和 `ad` 每次请求收取 0.5 积分。

## TikTok 广告资料库

### 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "tiktok_ad_library", "advertiserName": "NIKE Retail B.V.", "country": "DE", "sortBy": "published_asc", "limit": 14 } }'
```

提交 task 后，轮询 `GET /v1/async/task/{id}` 或通过 webhook 接收。参见 [异步 task](https://docs.querying.ai/zh/concepts/async-tasks.md)。300 条广告的搜索约需一分钟。

### 分析竞品广告

三个请求即可完成一次竞品分析：

1. 用竞品名称的开头部分发送 `advertisers`，得到资料库所知的确切名称和 ID。
2. 把该名称放入 `advertiserName` 发送 `search`，列出该广告主的广告。`sortBy` 按发布日期、最后展示日期或展示次数排序，`activeStatus` 只保留投放中或已停止的广告，`summary` 统计各形式的广告数和每周开始投放的广告数。
3. 用广告的 `libraryId` 发送 `ad`，得到落地页、付费方、定向、受众规模，以及按国家、年龄、性别划分的展示次数。

要按广告内容查找广告，请用 `query` 代替 `advertiserName`：它搜索文案、话题标签和广告主名称。

### 参数

* `action`：`search`（默认）、`advertisers` 或 `ad`。
* `country`：所有操作都必须提供。取值为 `AT`, `BE`, `BG`, `BR`, `CH`, `CY`, `CZ`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GB`, `GR`, `HR`, `HU`, `IE`, `IS`, `IT`, `LI`, `LT`, `LU`, `LV`, `MT`, `NL`, `NO`, `PL`, `PT`, `RO`, `SE`, `SI`, `SK`, `TR` 之一。`ALL` 以及列表之外的国家（如 `US`、`KR` 和 `JP`）会以 `400 VALIDATION_ERROR` 拒绝，因为资料库只覆盖这些地区。
* `query`：关键词。在 `search` 上，它按相关度匹配文案、话题标签和广告主，资料库最多统计 5,000 条广告。在 `advertisers` 上，它是广告主名称的开头部分，且必须提供。`search` 需要 `query` 或 `advertiserName`，不能同时提供。
* `advertiserName`：广告主的确切名称，例如 `NIKE Retail B.V.`。资料库统计它的全部广告。
* `libraryId`：广告的数字 ID，例如 `1879578148398450`。`ad` 必须提供。
* `activeStatus`：`all`（默认）、`active` 或 `inactive`。
* `mediaType`：`all`（默认）、`video` 或 `image`。
* `startDate`、`endDate`：`YYYY-MM-DD`。保留在这两天之间展示的广告。默认为最近 365 天。
* `sortBy`：`published_desc`（默认）、`published_asc`、`last_shown_desc`、`last_shown_asc`、`impressions_desc` 或 `impressions_asc`。它适用于 `advertiserName` 搜索，`query` 搜索始终按相关度排序。
* `limit`：1 到 300 条广告。默认 30。
* `cursor`：上一次响应的 `nextCursor`，用于读取其后的广告。

`search` 读取上面除 `libraryId` 之外的所有字段。`advertisers` 读取 `query` 和 `country`，`ad` 读取 `libraryId` 和 `country`。资料库无法搜索的值，或该操作不读取的字段，会以 `400 VALIDATION_ERROR` 拒绝，`details` 会指明字段。

### 读取更多广告

还有更多广告可读时，响应带有 `nextCursor`。把它作为 `cursor` 与同一搜索一起发送，即可收到后续广告，同样最多 `limit` 条。资料库没有更多广告时，`nextCursor` 为 `null`。游标只能用于返回它的那次搜索：`query`、`advertiserName`、`country`、`activeStatus`、`mediaType`、日期范围或 `sortBy` 不同，会以 `400 VALIDATION_ERROR` 拒绝，而 `limit` 可以改变。在资料库按相关度排序的 `query` 搜索中，两页交界处的少数广告可能重复或遗漏；用 `libraryId` 区分重复项。

### 查找广告主

`action` `advertisers` 最多返回 20 个名称以 `query` 开头的广告主。把确切名称作为 `advertiserName` 发送，即可搜索该广告主的广告。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "tiktok_ad_library", "action": "advertisers", "query": "nike", "country": "DE" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "advertisers",
  "country": "DE",
  "query": "nike",
  "returnedCount": 5,
  "advertisers": [
    {
      "advertiserId": "7587573238117498896",
      "advertiserName": "NIKE COM SRL",
      "country": null,
      "verified": null,
      "adCount": null
    }
  ]
}
```

每个广告主包含 `advertiserId` 和 `advertiserName`。资料库的建议不提供更多信息，所以 `country`、`adCount` 和 `verified` 为 `null`。广告主搜索收取 0.5 积分。

### 搜索响应示例

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "search",
  "country": "DE",
  "advertiserName": "NIKE Retail B.V.",
  "activeStatus": "all",
  "mediaType": "all",
  "sortBy": "published_asc",
  "totalCount": 20862,
  "returnedCount": 14,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiRDBZOVVUcnFNamhOQkhXVyIsImMiOiJleUpzWVhOMFgzTnZjblFpT2xzeE56WXdOakF5TVRnM01EQXdYU3dpYm1WNGRGOWpkWEp6YjNJaU9qRXlmUT09IiwicyI6MiwicCI6MTR9",
  "libraryUrl": "https://library.tiktok.com/ads?region=DE&start_time=1763856000000&end_time=1795391999000&adv_name=NIKE%20Retail%20B.V.&adv_biz_ids=&query_type=2&sort_type=create_time%2Casc&ad_type=0&ad_status=0",
  "ads": [
    {
      "position": 1,
      "libraryId": "1845598948737025",
      "libraryUrl": "https://library.tiktok.com/ads/detail/",
      "advertiserId": null,
      "advertiserName": "NIKE Retail B.V.",
      "isActive": null,
      "startDate": "2025-10-22",
      "endDate": "2025-12-21",
      "activeDays": 61,
      "platforms": ["TIKTOK"],
      "format": "VIDEO",
      "title": "Built to Move Different.",
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": { "min": 400000, "max": 500000 },
      "estimatedAudience": "400K-500K",
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUghNK4doIQWDyBoVB8FvvvEQmDDPMAupgfSf8~tplv-tiktokx-origin.jpeg"
      ],
      "videos": [
        {
          "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUghNK4doIQWDyBoVB8FvvvEQmDDPMAupgfSf8~tplv-tiktokx-origin.jpeg",
          "url": "https://library.tiktok.com/api/v1/cdn/1795365691/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTAwNTFjMDAxLXNnL29rbWhwZ2c4ZkFReU52UHJnRE5vOGZCNFZFQlFGRHZ1UEtHSWlvLw==/3cddf31b-4bd3-44fc-b813-42e1897d9536"
        }
      ],
      "category": null,
      "objective": null
    }
  ],
  "summary": {
    "ads": 14,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "NIKE Retail B.V.", "ads": 14 }
    ],
    "formats": { "IMAGE": 2, "VIDEO": 12 },
    "platforms": { "TIKTOK": 14 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [
      { "week": "2025-W42", "ads": 4 }
    ],
    "longestRunning": [
      {
        "libraryId": "1845598948737025",
        "advertiserName": "NIKE Retail B.V.",
        "isActive": null,
        "activeDays": 61,
        "title": "Built to Move Different."
      }
    ],
    "oldestStartDate": "2025-10-16",
    "newestStartDate": "2025-11-11",
    "medianActiveDays": 61
  }
}
```

* 响应会原样返回 `platform`、`action`、`country`、`query` 或 `advertiserName`、`activeStatus`、`mediaType` 和 `sortBy`。`totalCount` 是资料库统计的匹配广告数，在 `query` 搜索中最多到 5,000。`returnedCount` 统计 `ads` 中的广告数，资料库还有更多广告时 `hasMore` 为 `true`，可用 `nextCursor` 继续读取，`libraryUrl` 在广告资料库中打开同一搜索。
* 每条广告包含 `position`、`libraryId`、`libraryUrl`、`advertiserName`、`title`、`format`（`VIDEO`、`IMAGE` 或 `TEXT`）、`images`、`videos`（`url`、`previewUrl`）、`startDate`、`endDate`、`activeDays`、`impressions`（`min`、`max`）、`estimatedAudience`（资料库给出的范围，如 `400K-500K`）和 `platforms`（`TIKTOK`）。
* `startDate` 和 `endDate` 是资料库展示该广告的第一天和最后一天（UTC 日期）。`activeDays` 是从 `startDate` 到 `endDate` 的天数，两个日期都计入。资料库不提供花费。
* `activeStatus` 为 `active` 或 `inactive` 时，`isActive` 为 `true` 或 `false`；为 `all` 时为 `null`。
* `advertiserId`、`payer`、`linkUrl`、`landingDomain`、`utm` 和 `targeting` 在搜索中为 `null`，由 `ad` 填充。
* `summary` 统计本次响应中的广告：`ads`、`activeAds`、`advertisers`（广告最多的 10 个）、`formats`、`platforms`、`oldestStartDate`、`newestStartDate` 和 `medianActiveDays`，并包含 `launchesByWeek`（每个 ISO 周开始投放的广告数）和 `longestRunning`（`activeDays` 最大的 5 条广告）。搜索不含落地页，所以没有 `landingDomains` 和 `utmCampaigns`。
* 图片和视频 URL 已签名，读取后约 5 到 6 小时过期。请自行保存需要的文件。
* 没有匹配广告的搜索会以空的 `ads` 和广告数为 `0` 的 `summary` 完成。

### 资料库保留的范围

资料库展示在其 34 个地区投放的广告，并保留约 13 个月。它为每条广告提供首次和最后展示的日期以及展示次数范围，不公开花费。

### 打开单条广告

`action` `ad` 打开你发送的 `libraryId` 和 `country` 对应的广告。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "tiktok_ad_library", "action": "ad", "libraryId": "1879578148398450", "country": "DE" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "ad",
  "country": "DE",
  "libraryId": "1879578148398450",
  "ad": {
    "position": 1,
    "libraryId": "1879578148398450",
    "libraryUrl": "https://library.tiktok.com/ads/detail/",
    "advertiserId": "6876453864464188162",
    "advertiserName": "NIKE Retail B.V.",
    "isActive": null,
    "startDate": "2026-10-20",
    "endDate": "2026-11-08",
    "activeDays": 20,
    "platforms": ["TIKTOK"],
    "format": "VIDEO",
    "title": "Neue Winterausrüstung in Nike Factory Stores.",
    "body": null,
    "ctaText": "Learn more",
    "ctaType": null,
    "linkUrl": "https://www.nike.com/de/retail",
    "landingDomain": "nike.com",
    "utm": null,
    "payer": "INITIATIVE MEDIA B.V.",
    "impressions": { "min": 300000, "max": 400000 },
    "estimatedAudience": "300K-400K",
    "targeting": {
      "byCountry": [
        { "country": "DE", "ages": ["18-24"], "genders": ["FEMALE"] }
      ],
      "cities": [],
      "creatorInteractions": null,
      "customAudience": "No",
      "deviceModels": [],
      "excludesAudience": "No",
      "highSpendingPower": "No",
      "interests": null,
      "languages": [],
      "operatingSystems": ["ALL"],
      "provinces": ["Berlin"],
      "targetAudienceSize": "15.5M-18.9M",
      "videoInteractions": null
    },
    "reachedCountries": ["DE"],
    "images": [
      "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261013c7c72a61615657cc4f6482cd~tplv-tiktokx-origin.jpeg"
    ],
    "videos": [
      {
        "previewUrl": "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261013c7c72a61615657cc4f6482cd~tplv-tiktokx-origin.jpeg",
        "url": "https://library.tiktok.com/api/v1/cdn/1795365698/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTUxYzc5OS1zZy9vc21jZFFBbjhBZ1BlRWVWQU1iVmRVQ2tzUUQ0WEdrUlVMRVJoZi8=/9aa37923-f585-4393-b635-1409c7ce6656"
      }
    ],
    "category": "Apparel & Accessories",
    "objective": "Traffic"
  },
  "advertiser": {
    "advertiserId": "6876453864464188162",
    "advertiserName": "NIKE Retail B.V.",
    "payer": "INITIATIVE MEDIA B.V.",
    "account": {
      "verified": true,
      "accountType": "VERIFIED_BA",
      "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e0b0ac7b6ad6447a8e923fd1eb162f2c~tplv-tiktokx-cropcenter:168:168.jpeg",
      "displayName": "Nike",
      "followers": "9.4M",
      "profileUrl": "https://www.tiktok.com/share/user/208464585232822272",
      "username": "nike"
    },
    "registryCountry": "Netherlands"
  },
  "transparency": {
    "byCountry": [
      {
        "country": "DE",
        "impressions": "357K",
        "breakdowns": [
          { "impressions": "44K", "age": "18-24", "gender": "MALE" }
        ]
      }
    ],
    "totalImpressions": "300K-400K"
  }
}
```

* `ad` 包含搜索广告的字段，外加 `linkUrl`、`landingDomain`、`payer`（为广告付费的一方）、`category`、`objective`、`ctaText`、`advertiserId`、`reachedCountries` 和 `targeting`。
* `targeting` 包含 `byCountry`（每个国家的 `ages` 和 `genders`）、`provinces`、`cities`、`languages`、`interests`、`targetAudienceSize`（资料库给出的范围，如 `15.5M-18.9M`）、`customAudience`、`excludesAudience`、`highSpendingPower`、`operatingSystems`、`deviceModels`、`videoInteractions` 和 `creatorInteractions`。资料库没有为该广告公开的部分为 `null` 或空。
* `advertiser` 包含 `advertiserId`、`advertiserName`、`payer`、`registryCountry` 以及广告背后的 TikTok `account`（`username`、`displayName`、`verified`、`followers`、`accountType`、`profileUrl`、`avatarUrl`）。
* `transparency` 包含 `totalImpressions` 和 `byCountry`：每个国家的 `impressions`，以及按 `age` 和 `gender` 划分的 `breakdowns`。
* 资料库没有对应广告的 `libraryId` 会以 `PAGE_UNAVAILABLE` 失败。

## TikTok Creative Center

Creative Center 列出各国的热门广告，即 TikTok 为最近 7、30 或 180 天挑选的广告。它是排名样本，不是广告主的全部广告：广告主名称常常为空，也不提供日期、花费或展示次数。它为每条广告提供点击率、点赞数、成本水平、行业和目标。用它找出哪些开头钩子、形式和产品在某个市场有效。

### 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "tiktok_creative_center", "country": "US", "limit": 25 } }'
```

### 参数

* `action`：`search`（默认）或 `ad`。`advertisers` 会以 `400 VALIDATION_ERROR` 拒绝，因为 Creative Center 没有广告主查找。
* `country`：`search` 必须提供。取值为 `AE`, `AR`, `AU`, `BR`, `CA`, `CO`, `DE`, `ES`, `FR`, `GB`, `ID`, `IT`, `JP`, `KR`, `MX`, `MY`, `NL`, `PH`, `PK`, `RO`, `SA`, `SE`, `SG`, `TH`, `TR`, `US`, `VN`, `ZA` 之一。`ALL` 会被拒绝。
* `query`：关键词。
* `period`：`7`、`30`（默认）或 `180` 天。
* `industry`：行业 ID，例如 `21103000000`（Hardware & Electrical），即广告的 `industry.id` 所指的值。
* `objective`：`traffic`, `app_installs`, `conversions`, `video_views`, `reach`, `lead_generation`, `product_sales`, `app_promotion`。
* `adLanguage`：语言代码：`en`, `es`, `ar`, `vi`, `th`, `de`, `id`, `pt`, `fr`, `ms`, `nl`, `ja`, `it`, `ro`, `zh-Hant`, `ko`。
* `adFormat`：`spark`（助推创作者帖子的广告）或 `non_spark`。
* `sortBy`：`for_you`（默认）、`impression`、`ctr`、`play_2s_rate`、`play_6s_rate`、`cvr` 或 `like`。
* `limit`：1 到 200 条广告。默认 30。
* `cursor`：上一次响应的 `nextCursor`。
* `libraryId`：热门广告的数字 ID。`ad` 必须提供。

`search` 读取上面除 `libraryId` 之外的所有字段，`ad` 只读取 `libraryId`。对于同一个国家、周期和筛选条件的组合，Creative Center 最多列出约 400 到 500 条广告（`totalCount`）。

### 搜索响应示例

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_creative_center",
  "action": "search",
  "country": "US",
  "period": 30,
  "sortBy": "for_you",
  "totalCount": 183,
  "returnedCount": 25,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiUzJCUk5GZ2V4bkNsM1NXcyIsImciOjIsInMiOjYsInAiOjI1fQ",
  "libraryUrl": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en",
  "ads": [
    {
      "position": 1,
      "libraryId": "7705106910069080084",
      "libraryUrl": null,
      "advertiserId": null,
      "advertiserName": null,
      "isActive": null,
      "startDate": null,
      "endDate": null,
      "activeDays": null,
      "platforms": ["TIKTOK"],
      "format": "VIDEO",
      "width": 720,
      "height": 1280,
      "title": "No-BS Tool Video 103: Northern Tool + Equipment Wide Truck Toolbox",
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-51c799-sg/oAQ4uJuVEAkCTi0B2YczHAViMtauDHIKBpPBA~tplv-noop.image"
      ],
      "videos": [
        {
          "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-51c799-sg/oAQ4uJuVEAkCTi0B2YczHAViMtauDHIKBpPBA~tplv-noop.image",
          "url": "https://v16m-default.tiktokcdn.com/dd86ec10034c2f4740daf53e9bd6c280/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/oAMlOqB0IiATEFAdXQioXCBIAywNfmmu18gjwb/"
        }
      ],
      "aiSummary": null,
      "comments": null,
      "costLevel": 0,
      "ctrPercent": 0.66,
      "durationSeconds": 19.834,
      "industry": { "id": "21103000000", "name": "Hardware & Electrical" },
      "keywords": null,
      "likes": 787,
      "objectives": ["video_views"],
      "shares": null,
      "source": null,
      "videoUrls": {
        "1080p": "https://v16m-default.tiktokcdn.com/dd86ec10034c2f4740daf53e9bd6c280/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/oAMlOqB0IiATEFAdXQioXCBIAywNfmmu18gjwb/",
        "360p": "https://v16m-default.tiktokcdn.com/b36269b95476575962b9c114fc501dc3/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/o0NvZBpNAk4I2gfqugQFEnK7QB5fuCkcAgDEDZ/",
        "480p": "https://v16m-default.tiktokcdn.com/59590e737aed92b6a688cb20125bb307/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/ogfcNqEZ7n5EDE34BAIB2knfpNgg7FQDgKQBug/",
        "540p": "https://v16m-default.tiktokcdn.com/16951456d88cf46000321fb9be66eaa0/6b036fbb/video/tos/alisg/tos-alisg-ve-51c799-sg/oUfDB7pQBIAg2F65KQEncfgougEkZBDvqQNNpF/",
        "720p": "https://v16m-default.tiktokcdn.com/7be67d46e9a7a041e395d2bfabd195f2/6b036fbb/video/tos/alisg/tos-alisg-ve-51c799-sg/osfGceBcVAqbGTPRAaIIATCgED3LgJryVtPzNf/"
      },
      "voiceOver": null
    }
  ],
  "summary": {
    "ads": 25,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "Marco Seven", "ads": 1 }
    ],
    "formats": { "VIDEO": 25 },
    "platforms": { "TIKTOK": 25 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [],
    "longestRunning": [],
    "oldestStartDate": null,
    "newestStartDate": null,
    "medianActiveDays": null
  }
}
```

* 响应会原样返回 `platform`、`action`、`country`、`period`、`sortBy` 以及你传入的筛选条件。`totalCount` 是该组合下的热门广告数。
* 每条广告包含 `position`、`libraryId`、`title`、`advertiserName`（常为 `null`）、`format`、`ctrPercent`（以百分比表示的点击率）、`costLevel`、`likes`、`industry`（`id`、`name`）、`objectives`、`durationSeconds`、`width`、`height`、`voiceOver`、`images`、`videos` 和 `videoUrls`（按分辨率划分的视频文件，如 `360p` 和 `1080p`）。
* Creative Center 不提供 `startDate`、`endDate`、`impressions` 或 `libraryUrl`，所以这些字段为 `null`，`summary` 只统计形式、广告主和平台。
* 视频和图片 URL 已签名，读取后约 5 到 6 小时过期。

### 打开单条广告

`action` `ad` 按 `libraryId` 打开一条热门广告，并增加 `linkUrl`、`landingDomain`、`reachedCountries`、`comments`、`shares` 和 `source`（广告的制作来源，如 `TikTok Ads Manager`）。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "tiktok_creative_center", "action": "ad", "libraryId": "7699613362636095496" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_creative_center",
  "action": "ad",
  "libraryId": "7699613362636095496",
  "ad": {
    "position": 1,
    "libraryId": "7699613362636095496",
    "libraryUrl": null,
    "advertiserId": null,
    "advertiserName": "Bob Mills Furniture",
    "isActive": null,
    "startDate": null,
    "endDate": null,
    "activeDays": null,
    "platforms": ["TIKTOK"],
    "format": "VIDEO",
    "width": 720,
    "height": 1280,
    "title": "Better Sleep Starts with the Right Mattress",
    "body": null,
    "ctaText": null,
    "ctaType": null,
    "linkUrl": "https://www.bobmillsfurniture.com/sleep-experts",
    "landingDomain": "bobmillsfurniture.com",
    "utm": null,
    "payer": null,
    "impressions": null,
    "targeting": null,
    "reachedCountries": ["US"],
    "images": [
      "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o47taaAAR0LVnI7BhqzPAuKziAYczLByGJi4E~tplv-noop.image"
    ],
    "videos": [
      {
        "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o47taaAAR0LVnI7BhqzPAuKziAYczLByGJi4E~tplv-noop.image",
        "url": "https://v16m-default.tiktokcdn.com/474b4bf87f62a54743f28d85725bcaf2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oE9AQRij1FVAIezCN8Q3CWtGbD2MUAsgqg8e3f/"
      }
    ],
    "aiSummary": null,
    "comments": 0,
    "costLevel": 1,
    "ctrPercent": 0.2,
    "durationSeconds": 30.55,
    "industry": { "id": "23123000000", "name": "Sports & Fitness" },
    "keywords": null,
    "likes": 28,
    "objectives": ["traffic"],
    "shares": 0,
    "source": "TikTok Ads Manager",
    "videoUrls": {
      "1080p": "https://v16m-default.tiktokcdn.com/474b4bf87f62a54743f28d85725bcaf2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oE9AQRij1FVAIezCN8Q3CWtGbD2MUAsgqg8e3f/",
      "360p": "https://v16m-default.tiktokcdn.com/93487026a84b0472c46d3ff9471ee8f7/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oo1kCLCbgGVGt1GsCACGAAzbQefjqmDIfyIXQg/",
      "480p": "https://v16m-default.tiktokcdn.com/49d6ee93d4fc380675d41954037c55d1/6b036fca/video/tos/alisg/tos-alisg-ve-51c799-sg/okfRtfZroqDRIgEzhatFVDwDBABy2ENaWhQAQB/",
      "540p": "https://v16m-default.tiktokcdn.com/ce0699fb34b5ba3ccaa5251fba131ce2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUCWfxEEIBgqR32fDhFQapDtyZWaEDAVDBoNQh/",
      "720p": "https://v16m-default.tiktokcdn.com/d27a8eba19586eacc4784887cdd649e3/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/o0fNIDWVyhREjDDafOB4EzahgQFZBqAo2tDQhE/"
    },
    "voiceOver": false
  }
}
```

Creative Center 没有对应广告的 `libraryId` 会以 `PAGE_UNAVAILABLE` 失败。

## 价格

搜索开始时，按 `limit` 所要求的每 30 条广告预留 0.5 积分，按实际返回的每 30 条广告收取 0.5 积分，最少 0.5 积分。默认搜索（30 条广告）收取 0.5 积分，在广告资料库上 `limit` 为 300 的搜索预留 5 积分。`advertisers` 和 `ad` 每次请求收取 0.5 积分。只对已完成的请求收费。

## 相关

* [广告资料库对比](https://docs.querying.ai/zh/engines/ad-libraries.md)
* [Meta 广告资料库](https://docs.querying.ai/zh/engines/meta-ad-library.md)
* [引擎概览](https://docs.querying.ai/zh/engines/overview.md)
* [积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.