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

# 热门广告搜索

> 通过关键词搜索 TikTok 上的热门广告


<div className="inline-flex items-center gap-2 px-4 py-2 bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg">
  <span className="text-base">🪙</span>
  <span className="text-sm font-medium text-yellow-900 dark:text-yellow-100"><span className="font-semibold">2 credits</span><span className="text-yellow-700 dark:text-yellow-300 ml-1">每次请求</span></span>
</div>

## Copy for AI

<div className="my-6 rounded-xl border border-gray-200 bg-gray-50 p-5 dark:border-gray-800 dark:bg-gray-900/40">
  <div className="min-w-0">
    <p className="text-base font-semibold text-gray-900 dark:text-gray-100">🤖 让 AI 帮你写调用代码</p>
    <p className="mt-1 text-sm text-gray-700 dark:text-gray-300">点击按钮复制一段结构化提示词，可直接交给 ChatGPT、Claude 或其他 AI 助手生成接口调用代码。</p>
  </div>

  <div className="mt-4">
    <button
      type="button"
      className="inline-flex items-center gap-2 rounded-md border border-emerald-300 bg-emerald-50 px-3 py-2 text-sm font-medium text-emerald-800 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-100 dark:hover:bg-emerald-900/50"
      onClick={() => navigator.clipboard.writeText(`我需要调用以下 KeyAPI 接口，请根据提供的接口信息生成一份可直接运行的 Python 示例代码。

## 接口信息

Endpoint: GET https://api.keyapi.ai/v1/tk-ads/top_ads_search
Summary: 热门广告搜索

Required Headers:
- Authorization: Bearer <YOUR_API_KEY>

Parameters:
- keyword (Required): 无描述. Example: KurkurePakistan
- page (Optional): 页码.
- limit (Optional): 每页数量.
- country_code (Optional): 无描述.
- period (Optional): 无描述. Example: 180
- order_by (Optional): 排序方式.
- industry (Optional): 行业ID，从行业ID列表中获取（不传时不限制行业，即包含所有行业）.
- objective (Optional): 投放目标，（不传时不限制投放目标，即包含所有投放目标） 可选值（可多选）： 1=访问量、2=应用安装量、3=转化量、4=视频播放量、5=覆盖人数、8=潜在客户拓展、15=商品销量. Example: 1,2,3,4
- ad_language (Optional): 广告语言，（不传时不限制广告语言，即包含所有语言） 可选值（可多选）：en,es,ar,vi,th,de,id,pt,fr,ms,nl,ja,it,ro,zh-Hant,ko. Example: en,es,ar,vi,th
- ad_format (Optional): 广告样式，（不传时不限制广告样式，即包含所有样式） 可选值：1=Spark ads、2=非Spark ads.
- like (Optional): 点赞数，（不传时不限制点赞数量，即包含所有） 可选值(可多选)：1=前1~20%、2=前21~40%、3=前41~60%、4=前61~800%、5=前81~100%. Example: 1,2,3,4,5


## 代码要求

- 使用 Python \`requests\` 库
- 提供完整、可直接运行的示例
- 处理 HTTP 请求异常、超时以及非 2xx 响应
- 处理 JSON 解析异常
- 示例参数优先使用接口信息中提供的 Example
- 保持代码简洁，避免不必要的封装和复杂设计
`)}
    >
      ✨ 复制给 AI
    </button>
  </div>
</div>


## OpenAPI

````yaml zh/tiktok-ads-library.zh.openapi.json GET /v1/tk-ads/top_ads_search
openapi: 3.0.1
info:
  title: KeyAPI 文档
  description: tiktok-ads-library API 的中文参考文档，包含接口用途、参数说明、响应状态和示例结构。
  version: 1.0.0
servers:
  - url: https://api.keyapi.ai
    description: Production-KeyAPI
security: []
tags: []
paths:
  /v1/tk-ads/top_ads_search:
    get:
      tags: []
      summary: 热门广告搜索
      description: |
        通过关键词搜索 TikTok 上的热门广告
      parameters:
        - name: keyword
          in: query
          description: ''
          required: true
          example: KurkurePakistan
          schema:
            type: string
            example: KurkurePakistan
        - name: page
          in: query
          description: 页码
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: 每页数量
          required: false
          schema:
            type: integer
            default: 20
            maximum: 20
            minimum: 1
        - name: country_code
          in: query
          description: 国家代码，（不传时不限制国家，即包含所有）。从`/v1/tk-ads/get_priority_region`中获取
          required: false
          schema:
            type: string
            example: US,JP,AR,AU
        - name: period
          in: query
          description: ''
          required: false
          example: 180
          schema:
            type: integer
            enum:
              - 7
              - 30
              - 180
            default: 30
        - name: order_by
          in: query
          description: >-
            排序方式，可选值：

            for_you=推荐

            impression=曝光，至少观看视频一次的用户总数。

            ctr=点击率，点击率(CTR)是一个比率,即点击了广告的观看者数量与观看者总数的比值。计算方法是:点击次数除以观看者数量。

            play_2s_rate=2s完播率，至少播放 2 秒的次数除以视频播放总次数

            play_6s_rate=6s完播率，至少播放 6 秒的次数除以视频播放总次数

            cvr=转化率，转化率 (CVR)
            度量的是在视频的每一秒发生的转化（如关注、下载或购买）所占的百分比。计算方法是：转化次数除以互动次数。

            like=点赞数
          required: false
          example: ''
          schema:
            type: string
            enum:
              - for_you
              - impression
              - ctr
              - play_2s_rate
              - play_6s_rate
              - cvr
              - like
            default: for_you
        - name: industry
          in: query
          description: 行业ID，从行业ID列表中获取（不传时不限制行业，即包含所有行业）
          required: false
          schema:
            type: string
            example: 27999000000,27103000000
        - name: objective
          in: query
          description: |-
            投放目标，（不传时不限制投放目标，即包含所有投放目标）
            可选值（可多选）： 1=访问量、2=应用安装量、3=转化量、4=视频播放量、5=覆盖人数、8=潜在客户拓展、15=商品销量
          required: false
          schema:
            type: string
            example: 1,2,3,4
        - name: ad_language
          in: query
          description: |-
            广告语言，（不传时不限制广告语言，即包含所有语言）
            可选值（可多选）：en,es,ar,vi,th,de,id,pt,fr,ms,nl,ja,it,ro,zh-Hant,ko
          required: false
          schema:
            type: string
            example: en,es,ar,vi,th
        - name: ad_format
          in: query
          description: |-
            广告样式，（不传时不限制广告样式，即包含所有样式）
            可选值：1=Spark ads、2=非Spark ads
          required: false
          schema:
            type: string
        - name: like
          in: query
          description: >-
            点赞数，（不传时不限制点赞数量，即包含所有）可选值(可多选)：1=前1~20%、2=前21~40%、3=前41~60%、4=前61~800%、5=前81~100%
          required: false
          schema:
            type: string
            example: 1,2,3,4,5
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
              example:
                code: 0
                message: success
                data:
                  materials:
                    - ad_title: >-
                        Masalaydaar Tarkay, Karak Krunch Kar Ke - Sab Hogaye
                        KrazyForKurkure!
                      brand_name: KurkurePakistan
                      cost: 2
                      ctr: 0.38
                      favorite: false
                      id: '7552078920880619527'
                      industry_key: label_27101000000
                      is_search: false
                      like: 2152849
                      objective_key: campaign_objective_reach
                      video_info:
                        vid: v14033g50000d93a40fog65sgujaemn0
                        duration: 15.019
                        cover: >-
                          https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oYmEEquhABAgo65E41i8Am1A5BnwWA8IIafCGi~tplv-noop.image?dr=18692&refresh_token=3e3ac8cf&x-expires=1789393503&x-signature=n9fUX0u9Z5ItPNTWoXQRuRHJ14A%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v14033g50000d93a40fog65sgujaemn0
                        video_url:
                          1080p: >-
                            https://v16m-default.tiktokcdn.com/955090cb9c916a426c59a5a157e6e43c/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oo7fIaCTDAyExHb1GII1eQ6AD1yGhLe42gIt2G/?a=0&bti=NTU4QDM1NGA%3D&&bt=3699&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=aGk1PDk3PDY6Mzk3M2c7NEBpM3BkeHY5cjNkPDMzODYzNEAuNDAyNjQ2XmExMzAvM2NhYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          360p: >-
                            https://v16m-default.tiktokcdn.com/f81fd15c963706418668a20979389fea/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/ogABII22TDKzt61eAGCzvuKhLQ4IgEeb0Gf7D1/?a=0&bti=NTU4QDM1NGA%3D&&bt=637&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=NTg6NDdoZjNpM2c5ZWY1NEBpM3BkeHY5cjNkPDMzODYzNEBeXi1jMWJeNjIxYi5eNGMzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          480p: >-
                            https://v16m-default.tiktokcdn.com/13f109c2dfb52078173aeaaf9c9c85d5/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8BRQe6fGDHTLu2G1DIt25I0hCgE71IAexbP4A/?a=0&bti=NTU4QDM1NGA%3D&&bt=938&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=ZTY8aGc2OWRlN2c1ODZoNEBpM3BkeHY5cjNkPDMzODYzNEAvYi4tLWNiNmExLV9hYjY1YSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          540p: >-
                            https://v16m-default.tiktokcdn.com/00d0d1bf5360cb7555b4e373199406dc/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUEGThQe2212GC17qv4DpIWAI3g0D6CIfAeLbt/?a=0&bti=NTU4QDM1NGA%3D&&bt=1285&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=PDxpZzU4aWVoZWg4Omg0N0BpM3BkeHY5cjNkPDMzODYzNEAxLzFgLTYxNmAxLzNjMTAzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                          720p: >-
                            https://v16m-default.tiktokcdn.com/822724f69c9d4e45b6faa141e0833297/6aa7fa5f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oEbbPD12AeZE6Q0T12gLI4IhICfe8D0D3AGtG7/?a=0&bti=NTU4QDM1NGA%3D&&bt=1852&ft=cApXJCz7ThWH3DpDLGZmo0P&mime_type=video_mp4&rc=ZDVkZTk7Zzg3aTo5ZWVpZEBpM3BkeHY5cjNkPDMzODYzNEBfNC4uNDU1NTYxYWMuLy1jYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914154448470D7C13C73CB14AF8F7&btag=e000b8000
                        width: 720
                        height: 1280
                  pagination:
                    has_more: false
                    page: 1
                    size: 20
                    total_count: 1
                requestId: 0af59e6a-2544-45c3-898f-36b6b4985107
          headers: {}
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      deprecated: false
      security:
        - JWT Bearer: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request GET \
              --url 'https://api.keyapi.ai/v1/tk-ads/top_ads_search?keyword=KurkurePakistan&page=1&limit=20&period=180&objective=1%2C2%2C3%2C4&ad_language=en%2Ces%2Car%2Cvi%2Cth&like=1%2C2%2C3%2C4%2C5' \
              --header 'Authorization: Bearer <YOUR_API_KEY>'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.get(
                'https://api.keyapi.ai/v1/tk-ads/top_ads_search',
                params={"keyword":"KurkurePakistan","page":1,"limit":20,"period":180,"objective":"1,2,3,4","ad_language":"en,es,ar,vi,th","like":"1,2,3,4,5"},
                headers={'Authorization': 'Bearer <YOUR_API_KEY>'}
            )
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const params = new
            URLSearchParams({"keyword":"KurkurePakistan","page":1,"limit":20,"period":180,"objective":"1,2,3,4","ad_language":"en,es,ar,vi,th","like":"1,2,3,4,5"});


            const response = await
            fetch(`https://api.keyapi.ai/v1/tk-ads/top_ads_search?${params}`, {
              method: 'GET',
              headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
            });

            const data = await response.json();

            console.log(data);
components:
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            example:
              code: 400
              data: null
              message: 'Missing required parameter: handle'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            example:
              code: 401
              data: null
              message: apiKey is null
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            example:
              code: 402
              data: null
              message: apiKey quota is not enough
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            example:
              code: 429
              data: null
              message: qps limit exceeded
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            example:
              code: 500
              data: null
              message: Internal server error
  securitySchemes:
    JWT Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |-
        接口鉴权凭证。请在请求 Header 中传入 `Authorization: Bearer <YOUR_API_KEY>`。
        可在 [Dashboard](https://keyapi.ai/app/dashboard) 获取你的 API Key。

````