> ## 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.

# 热门广告详情

> 广告信息（地区、投放目标、行业、品牌名称、落地页、广告标题、投放效果）

<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_detail
Summary: 热门广告详情

Required Headers:
- Authorization: Bearer <YOUR_API_KEY>

Parameters:
- material_id (Required): 目标ID，可从\`/ads/top_ad_list\`中获取，或\`https://ads.tiktok.com/business/creativecenter/topads/7469861356595134480/pc/zh?from=001110&period=180\` material_id = 7469861356595134480. Example: 7552078920880619527


## 代码要求

- 使用 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_detail
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_detail:
    get:
      tags: []
      summary: 热门广告详情
      description: 广告信息（地区、投放目标、行业、品牌名称、落地页、广告标题、投放效果）
      parameters:
        - name: material_id
          in: query
          description: >-
            目标ID，可从`/ads/top_ad_list`中获取，或`https://ads.tiktok.com/business/creativecenter/topads/7469861356595134480/pc/zh?from=001110&period=180`
            material_id = 7469861356595134480
          required: true
          example: '7552078920880619527'
          schema:
            type: string
            example: '7552078920880619527'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      country_code:
                        type: array
                        items:
                          type: string
                        description: 地区
                      objectives:
                        type: array
                        items:
                          type: string
                        description: 投放目标
                      industry_key:
                        type: string
                        description: 行业
                      ad_title:
                        type: string
                        description: 广告标题
                      brand_name:
                        type: string
                        description: 品牌名称
                      landing_page:
                        type: string
                      highlight_text:
                        type: string
                        description: 创意摘要
                      comment:
                        type: integer
                        description: 评论数
                      share:
                        type: integer
                        description: 转发量
                      ctr:
                        type: number
                        description: |-
                          点击率(CTR)度量的是每一秒在观看时
                          点击了广告的观看者所占的百分比。计
                          算方法是:点击次数除以播放次数。
                      cost:
                        type: integer
                        description: 预算，2=高预算
                      like:
                        type: integer
                        description: 点赞数
                      source:
                        type: string
                        description: 来源
                    required:
                      - ad_title
                      - comment
                      - share
                      - ctr
                      - cost
                      - country_code
                      - objectives
                      - industry_key
                      - like
                      - landing_page
                      - source
                      - highlight_text
                required:
                  - code
                  - message
                  - data
              example:
                code: 0
                message: success
                data:
                  ad_title: >-
                    Masalaydaar Tarkay, Karak Krunch Kar Ke - Sab Hogaye
                    KrazyForKurkure!
                  brand_name: KurkurePakistan
                  comment: 11752
                  cost: 2
                  country_code:
                    - PK
                  ctr: 0.38
                  favorite: false
                  has_summary: false
                  highlight_text: ''
                  id: '7552078920880619527'
                  industry_key: label_27101000000
                  is_search: false
                  keyword_list: null
                  landing_page: >-
                    https://www.foodpanda.pk/darkstore/r1vf/pandamart-bahadurabad-khi/campaign/banner-69c51812c6d43c12bf5d9826?utm_campaign=coop_coop_web_dma_aut_aa_FP_PK_Kurkure&utm_medium=coops&utm_source=tiktok&utm_id=__CAMPAIGN_ID__
                  like: 2152849
                  objective_key: campaign_objective_reach
                  objectives:
                    - label: campaign_objective_reach
                      value: 5
                  pattern_label: []
                  share: 3181
                  source: TikTok Ads Manager
                  source_key: 1
                  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=4602ec8a&x-expires=1789389896&x-signature=7HDPZtA1WyKzn5Wc6yrG0WHTTfc%3D&t=9276707c&ps=14f1eb3e&shp=9e36835a&shcp=317596d8&idc=my&VideoID=v14033g50000d93a40fog65sgujaemn0
                    video_url:
                      1080p: >-
                        https://v16m-default.tiktokcdn.com/875a8f276d9aaa989cc277d715761d93/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/oo7fIaCTDAyExHb1GII1eQ6AD1yGhLe42gIt2G/?a=0&bti=NTU4QDM1NGA%3D&&bt=3699&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=aGk1PDk3PDY6Mzk3M2c7NEBpM3BkeHY5cjNkPDMzODYzNEAuNDAyNjQ2XmExMzAvM2NhYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      360p: >-
                        https://v16m-default.tiktokcdn.com/fb2b778a3e00c07daa1c66a62336a01f/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/ogABII22TDKzt61eAGCzvuKhLQ4IgEeb0Gf7D1/?a=0&bti=NTU4QDM1NGA%3D&&bt=637&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=NTg6NDdoZjNpM2c5ZWY1NEBpM3BkeHY5cjNkPDMzODYzNEBeXi1jMWJeNjIxYi5eNGMzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      480p: >-
                        https://v16m-default.tiktokcdn.com/ed6034a1a70ddc85c926d864783a5335/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8BRQe6fGDHTLu2G1DIt25I0hCgE71IAexbP4A/?a=0&bti=NTU4QDM1NGA%3D&&bt=938&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=ZTY8aGc2OWRlN2c1ODZoNEBpM3BkeHY5cjNkPDMzODYzNEAvYi4tLWNiNmExLV9hYjY1YSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      540p: >-
                        https://v16m-default.tiktokcdn.com/98f7c454750011c813c8341198877814/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUEGThQe2212GC17qv4DpIWAI3g0D6CIfAeLbt/?a=0&bti=NTU4QDM1NGA%3D&&bt=1285&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=PDxpZzU4aWVoZWg4Omg0N0BpM3BkeHY5cjNkPDMzODYzNEAxLzFgLTYxNmAxLzNjMTAzYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                      720p: >-
                        https://v16m-default.tiktokcdn.com/30b69e12c23bc0259b512c23e24b8795/6aa7ec48/video/tos/alisg/tos-alisg-ve-0051c001-sg/oEbbPD12AeZE6Q0T12gLI4IhICfe8D0D3AGtG7/?a=0&bti=NTU4QDM1NGA%3D&&bt=1852&ft=cApXJCz7ThWHG7qDLGZmo0P&mime_type=video_mp4&rc=ZDVkZTk7Zzg3aTo5ZWVpZEBpM3BkeHY5cjNkPDMzODYzNEBfNC4uNDU1NTYxYWMuLy1jYSNrYmdkMmRjMTBhLS1kMDFzcw%3D%3D&vvpl=1&l=20260914144441B141D3E23966E171E9DC&btag=e000b8000
                    width: 720
                    height: 1280
                  voice_over: false
                requestId: 18ea5bb9-bf54-484b-830d-2d4ff85c45f8
          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_detail?material_id=7552078920880619527' \
              --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_detail',
                params={"material_id":"7552078920880619527"},
                headers={'Authorization': 'Bearer <YOUR_API_KEY>'}
            )
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const params = new
            URLSearchParams({"material_id":"7552078920880619527"});


            const response = await
            fetch(`https://api.keyapi.ai/v1/tk-ads/top_ads_detail?${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。

````