---
title: "获取广告关键帧分析/Get ad keyframe analysis"
method: POST
path: "/api/v1/tiktok/ads/get_ad_keyframe_analysis"
tags: ["TikTok-Ads-API"]
---

# 获取广告关键帧分析/Get ad keyframe analysis

`POST /api/v1/tiktok/ads/get_ad_keyframe_analysis`

## Request

- Base URL: `https://api.tikhub.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tikhub.io/api/v1/tiktok/ads/get_ad_keyframe_analysis`
- Auth: HTTP bearer

# [中文]
### 用途:
- 获取广告视频的关键帧分析，了解视频在不同时间点的观众留存情况
- 分析哪些时间点最吸引观众，哪些时间点观众流失最多
- 帮助优化广告视频结构，提高观看完成率

### 参数:
- material_id: 广告素材ID，必填参数
- metric: 分析指标，可选值：
  - retain_ctr: 留存点击率（默认）
  - retain_cvr: 留存转化率
  - click_cnt: 点击次数
  - convert_cnt: 转化次数
  - play_retain_cnt: 播放留存量
- cookie: 自定义Cookie字符串，可选参数，可以使用自己的Cookie来获取更多数据

### 返回内容说明:
- `keyframe_data`: 关键帧数据
  - `time_points`: 时间点列表（秒）
  - `retention_rates`: 对应时间点的留存率（百分比）
  - `drop_points`: 流失率较高的时间点
  - `highlight_points`: 观众兴趣较高的时间点

### 示例响应:
```json
{
  "code": 200,
  "router": "/api/v1/tiktok/ads/get_ad_keyframe_analysis",
  "params": {
    "material_id": "7213258221116751874"
  },
  "data": {
    "keyframe_data": {
      "time_points": [0, 1, 2, 3, 4, 5],
      "retention_rates": [100, 95, 88, 82, 78, 75],
      "drop_points": [2, 4],
      "highlight_points": [1, 5]
    }
  }
}
```

# [English]
### Purpose:
- Get keyframe analysis of ad videos to understand audience retention at different time points
- Analyze which time points attract viewers most and where viewers drop off
- Help optimize ad video structure to improve completion rates

### Parameters:
- material_id: Ad material ID, required parameter
- metric: Analysis metric, options:
  - retain_ctr: Retention CTR (default)
  - retain_cvr: Retention CVR
  - click_cnt: Click count
  - convert_cnt: Conversion count
  - play_retain_cnt: Play retention count
- cookie: Custom Cookie string, optional parameter, can be used to fetch more data

### Return Description:
- `keyframe_data`: Keyframe data
  - `time_points`: List of time points (seconds)
  - `retention_rates`: Retention rates at corresponding time points (percentage)
  - `drop_points`: Time points with high drop-off rates
  - `highlight_points`: Time points with high viewer interest

### Example Response:
```json
{
  "code": 200,
  "router": "/api/v1/tiktok/ads/get_ad_keyframe_analysis",
  "params": {
    "material_id": "7213258221116751874"
  },
  "data": {
    "keyframe_data": {
      "time_points": [0, 1, 2, 3, 4, 5],
      "retention_rates": [100, 95, 88, 82, 78, 75],
      "drop_points": [2, 4],
      "highlight_points": [1, 5]
    }
  }
}
```

## Request body

- BodyGetAdKeyframeAnalysisApiV1TiktokAdsGetAdKeyframeAnalysisPost
  - `material_id` string, required: 广告素材ID/Ad material ID
  - `metric` string: 分析指标/Analysis metric (retain_ctr, retain_cvr, click_cnt, convert_cnt, play_retain_cnt)
  - `cookie` string: 自定义Cookie字符串（可选）

## Response `200`

Successful Response

- ResponseModel
  - `code` integer: HTTP status code | HTTP状态码
  - `request_id` string, nullable: Unique request identifier | 唯一请求标识符
  - `message` string: Response message (EN-US) | 响应消息 (English)
  - `message_zh` string: Response message (ZH-CN) | 响应消息 (中文)
  - `support` string: Support message | 支持消息
  - `time` string: The time the response was generated | 生成响应的时间
  - `time_stamp` integer: The timestamp the response was generated | 生成响应的时间戳
  - `time_zone` string: The timezone of the response time | 响应时间的时区
  - `docs` string, nullable: Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接
  - `cache_message` string, nullable: Cache message (EN-US) | 缓存消息 (English)
  - `cache_message_zh` string, nullable: Cache message (ZH-CN) | 缓存消息 (中文)
  - `cache_url` string, nullable: The URL to access the cached result | 访问缓存结果的 URL
  - `router` string: The endpoint that generated this response | 生成此响应的端点
  - `params` unknown
  - `data` unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-08** `96a122a5f220`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-09-01** `50f9ec6e1cd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/changes/api/v1/tiktok/ads/get_ad_keyframe_analysis/post.md)

---

[API](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi.md) - [All operations](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/llms.txt) - [OpenAPI document](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/revisions/86a3483c705a?raw)