---
title: "获取搜索关键词推荐 V2/Fetch search keyword suggestions V2"
method: POST
path: "/api/v1/douyin/search/fetch_search_suggest_v2"
tags: ["Douyin-Search-API"]
---

# 获取搜索关键词推荐 V2/Fetch search keyword suggestions V2

`POST /api/v1/douyin/search/fetch_search_suggest_v2`

## 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/douyin/search/fetch_search_suggest_v2`
- Auth: HTTP bearer

# [中文]
### 用途:
- 获取抖音搜索关键词的联想推荐结果（V2 版本）。
- 根据用户已输入的关键词前缀，返回相关搜索词建议，用于实现搜索框实时补全。

### 备注:
- 返回条数由抖音决定，不支持指定数量。
- `history_words` 为可选项，传入用户此前搜索过的词（英文逗号分隔）会影响联想词排序。
- 相比 V1，V2 直接给出纯词列表 `words`，无需再从原始结构中提取。

### 参数:
- keyword: 已输入的关键词，如 "人工智能"
- history_words: 可选，历史搜索词，如 "猫咪,美食"

### 请求体示例：
```json
payload = {
    "keyword": "人工智能",
    "history_words": ""
}
```

### 返回（部分常用字段，实际返回字段更多，一切以实际响应为准）:
- `words[]`: 联想词字符串列表（多数场景只需要这个）
- `items[]`: 联想词完整条目，需要高亮位置或来源信息时使用
  - `content`: 联想词内容
  - `pos[]`: 命中位置（`begin` 起始字符位置、`end` 结束字符位置）
  - `word_record`: 词记录（`group_id` 词组ID、`words_source` 词来源等）
  - `extra_info`: 附加信息
- `virtual[]`: 虚拟联想词列表（部分关键词才有）
- `empty_reason`: 没有联想词时给出的原因（仅在结果为空时返回）

# [English]
### Purpose:
- Fetch Douyin search keyword suggestions (V2).
- Returns suggested keywords for the entered prefix, for real-time search-box completion.

### Notes:
- The number of suggestions is decided by Douyin and cannot be specified.
- `history_words` is optional; passing the user's previous search words (comma separated)
  affects the ranking of the suggestions.
- Compared with V1, V2 returns a plain `words` list directly, no extraction needed.

### Parameters:
- keyword: The entered keyword, e.g., "Artificial Intelligence"
- history_words: Optional history search words, e.g., "cat,food"

### Request Body Example:
```json
payload = {
    "keyword": "Artificial Intelligence",
    "history_words": ""
}
```

### Response (common fields, actual response may contain more fields):
- `words[]`: Plain list of suggested keywords (enough for most use cases)
- `items[]`: Full suggestion entries, use when highlight positions or sources are needed
  - `content`: Suggested keyword
  - `pos[]`: Matched position (`begin` / `end` character positions)
  - `word_record`: Word record (`group_id`, `words_source`, etc.)
  - `extra_info`: Extra information
- `virtual[]`: Virtual suggestion list (only for some keywords)
- `empty_reason`: Why the suggestion list is empty (only returned when there is no result)

## Request body

- SearchSuggestV2Request
  - `keyword` string: 需要联想的关键词/The keyword to be suggested
  - `history_words` string: 可选，用户的历史搜索词（英文逗号分隔），会影响联想词的排序/Optional, the user's history search words (comma separated), affects the ranking of suggestions

## 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/douyin/search/fetch_search_suggest_v2/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)