J/daren

Fork 0

wanjia 5eab14304c 增加飞书模块

2025-05-29 16:11:38 +08:00

17 KiB

Raw Blame History

Discovery模块API文档

概述

Discovery (发现) 模块是一个用于搜索和发现创作者/达人的系统。该模块提供了一系列RESTful API接口，用于创建搜索会话、搜索创作者和查询历史搜索结果。

通用响应格式

所有API响应都遵循以下统一的JSON格式：

{
  "code": 200,      // 状态码，200表示成功，其他值表示错误
  "message": "成功", // 响应消息
  "data": {}        // 响应数据，可能是对象、数组或null
}

分页响应格式

使用分页的接口将返回以下格式：

{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 100,                  // 总记录数
    "next": "下一页URL或null",      // 下一页链接
    "previous": "上一页URL或null",  // 上一页链接
    "results": []                   // 当前页的数据
  }
}

认证方式

所有接口都需要使用自定义Token认证，请在HTTP请求头中添加以下字段：

Authorization: Token your_token_here

1. 搜索会话管理 (Sessions)

搜索会话保存了搜索历史记录和搜索结果，便于追踪和回顾之前的搜索。

1.1 获取搜索会话列表

URL: /sessions/
方法: GET
描述: 获取所有搜索会话的列表
请求参数:
- page: 页码，默认为1
- page_size: 每页记录数，默认为20，最大为100

响应数据:

{
  "code": 200,
  "message": "获取搜索会话列表成功",
  "data": {
    "count": 10,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 1,
        "session_number": 1,
        "creator_count": 20,
        "shoppable_creators": 15,
        "avg_followers": 10000.5,
        "avg_gmv": 5000.25,
        "avg_video_views": 20000.75,
        "date_created": "2023-06-01"
      }
    ]
  }
}

1.2 创建搜索会话

URL: /sessions/
方法: POST
描述: 创建一个新的搜索会话

请求参数:

{
  "session_number": 1,             // 可选，默认为1
  "creator_count": 0,              // 可选，默认为0
  "shoppable_creators": 0,         // 可选，默认为0
  "avg_followers": 0,              // 可选，默认为0
  "avg_gmv": 0,                    // 可选，默认为0
  "avg_video_views": 0,            // 可选，默认为0
  "date_created": "2023-06-01"     // 可选，默认为当前日期
}

响应数据:

{
  "code": 200,
  "message": "创建搜索会话成功",
  "data": {
    "id": 1,
    "session_number": 1,
    "creator_count": 0,
    "shoppable_creators": 0,
    "avg_followers": 0,
    "avg_gmv": 0,
    "avg_video_views": 0,
    "date_created": "2023-06-01"
  }
}

1.3 获取搜索会话详情

URL: /sessions/{id}/
方法: GET
描述: 获取指定ID的搜索会话详情，包含相关的创作者数据
请求参数: 无

响应数据:

{
  "code": 200,
  "message": "获取搜索会话详情成功",
  "data": {
    "id": 1,
    "session_number": 1,
    "creator_count": 20,
    "shoppable_creators": 15,
    "avg_followers": 10000.5,
    "avg_gmv": 5000.25,
    "avg_video_views": 20000.75,
    "date_created": "2023-06-01",
    "creators": [
      {
        "id": 1,
        "session": 1,
        "name": "创作者名称",
        "avatar": "https://example.com/avatar.jpg",
        "category": "Sports & Outdoor",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-2",
        "followers": 15000,
        "gmv": 8000,
        "items_sold": 500,
        "avg_video_views": 25000,
        "has_ecommerce": true,
        "tiktok_url": "https://tiktok.com/@name",
        "hashtags": "#sport#fitness#outdoor",
        "trends": "summer fitness",
        "profile": "tiktok"
      }
    ]
  }
}

1.4 更新搜索会话

URL: /sessions/{id}/
方法: PUT/PATCH
描述: 更新指定ID的搜索会话信息
请求参数: 同创建搜索会话

响应数据:

{
  "code": 200,
  "message": "更新搜索会话成功",
  "data": {
    "id": 1,
    "session_number": 2,
    "creator_count": 25,
    "shoppable_creators": 18,
    "avg_followers": 12000.5,
    "avg_gmv": 6000.25,
    "avg_video_views": 22000.75,
    "date_created": "2023-06-01"
  }
}

1.5 删除搜索会话

URL: /sessions/{id}/
方法: DELETE
描述: 删除指定ID的搜索会话
请求参数: 无

响应数据:

{
  "code": 200,
  "message": "删除搜索会话成功",
  "data": null
}

1.6 获取会话创作者列表

URL: /sessions/{id}/results/
方法: GET
描述: 获取指定会话的搜索结果（创作者列表）
请求参数:
- page: 页码，默认为1
- page_size: 每页记录数，默认为20，最大为100

响应数据:

{
  "code": 200,
  "message": "获取会话创作者列表成功",
  "data": {
    "count": 20,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 1,
        "session": 1,
        "name": "创作者名称",
        "avatar": "https://example.com/avatar.jpg",
        "category": "Sports & Outdoor",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-2",
        "followers": 15000,
        "gmv": 8000,
        "items_sold": 500,
        "avg_video_views": 25000,
        "has_ecommerce": true,
        "tiktok_url": "https://tiktok.com/@name",
        "hashtags": "#sport#fitness#outdoor",
        "trends": "summer fitness",
        "profile": "tiktok"
      }
    ]
  }
}

1.7 获取会话摘要

URL: /sessions/summary/
方法: GET
描述: 获取所有会话的摘要数据，用于展示在表格中
请求参数: 无

响应数据:

{
  "code": 200,
  "message": "获取会话摘要列表成功",
  "data": [
    {
      "id": 1,
      "session_number": 1,
      "date": "2023-06-01",
      "creator_count": 20,
      "shoppable_creators": 15,
      "avg_followers": 10000.5,
      "avg_gmv": 5000.25,
      "avg_video_views": 20000.75
    }
  ]
}

1.8 搜索会话

URL: /sessions/search/
方法: GET
描述: 根据关键词搜索会话，支持模糊匹配
请求参数:
- keyword: 搜索关键词（必填），可以是会话ID、会话编号、日期或日期的一部分（如年份"2025"或月份"6"）
搜索说明:
- 支持按会话ID或会话编号精确搜索
- 支持按完整日期格式（如"2023-06-01"）搜索
- 支持按年份（如"2025"）搜索该年的所有会话
- 支持按月份数字（1-12）或月份名称（如"june"、"六月"）搜索
- 支持模糊匹配ID和会话编号

响应数据:

{
  "code": 200,
  "message": "搜索会话成功，关键词: 2025",
  "data": [
    {
      "id": 1,
      "session_number": 1,
      "date": "2025-06-01",
      "creator_count": 20,
      "shoppable_creators": 15,
      "avg_followers": 10000.5,
      "avg_gmv": 5000.25,
      "avg_video_views": 20000.75
    },
    {
      "id": 2,
      "session_number": 2,
      "date": "2025-07-15",
      "creator_count": 18,
      "shoppable_creators": 12,
      "avg_followers": 12000.5,
      "avg_gmv": 6000.25,
      "avg_video_views": 25000.75
    }
  ]
}

2. 创作者管理 (Creators)

创作者是系统中的核心数据实体，代表平台上的内容创作者/达人。

2.1 获取创作者列表

URL: /creators/
方法: GET
描述: 获取所有创作者的列表
请求参数:
- page: 页码，默认为1
- page_size: 每页记录数，默认为20，最大为100

响应数据:

{
  "code": 200,
  "message": "获取创作者列表成功",
  "data": {
    "count": 100,
    "next": "http://example.com/api/creators/?page=2",
    "previous": null,
    "results": [
      {
        "id": 1,
        "session": 1,
        "name": "创作者名称",
        "avatar": "https://example.com/avatar.jpg",
        "category": "Sports & Outdoor",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-2",
        "followers": 15000,
        "gmv": 8000,
        "items_sold": 500,
        "avg_video_views": 25000,
        "has_ecommerce": true,
        "tiktok_url": "https://tiktok.com/@name",
        "hashtags": "#sport#fitness#outdoor",
        "trends": "summer fitness",
        "profile": "tiktok"
      }
    ]
  }
}

2.2 获取创作者详情

URL: /creators/{id}/
方法: GET
描述: 获取指定ID的创作者详细信息
请求参数: 无

响应数据:

{
  "code": 200,
  "message": "获取创作者详情成功",
  "data": {
    "id": 1,
    "session": 1,
    "name": "创作者名称",
    "avatar": "https://example.com/avatar.jpg",
    "category": "Sports & Outdoor",
    "ecommerce_level": "L3",
    "exposure_level": "KOL-2",
    "followers": 15000,
    "gmv": 8000,
    "items_sold": 500,
    "avg_video_views": 25000,
    "has_ecommerce": true,
    "tiktok_url": "https://tiktok.com/@name",
    "hashtags": "#sport#fitness#outdoor",
    "trends": "summer fitness",
    "profile": "tiktok"
  }
}

2.3 搜索创作者

URL: /creators/search/
方法: POST
描述: 根据多种条件搜索创作者，会自动创建搜索会话并保存搜索结果

请求参数:

{
  "query": "运动",              // 可选，搜索关键词
  "category": "Sports & Outdoor", // 可选，类别
  "ecommerce_level": "L3",        // 可选，电商等级（L1-L5）
  "exposure_level": "KOL-2",      // 可选，曝光等级
  "hashtag": "fitness",           // 可选，标签
  "trend": "summer",              // 可选，趋势
  "profile": "tiktok"             // 可选，平台（tiktok、instagram等）
}

响应数据:

{
  "code": 200,
  "message": "搜索创作者成功",
  "data": {
    "id": 1,
    "session_number": 1,
    "creator_count": 5,
    "shoppable_creators": 3,
    "avg_followers": 12000.5,
    "avg_gmv": 5500.25,
    "avg_video_views": 20500.75,
    "date_created": "2023-06-01",
    "creators": [
      {
        "id": 1,
        "session": 1,
        "name": "创作者名称",
        "avatar": "https://example.com/avatar.jpg",
        "category": "Sports & Outdoor",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-2",
        "followers": 15000,
        "gmv": 8000,
        "items_sold": 500,
        "avg_video_views": 25000,
        "has_ecommerce": true,
        "tiktok_url": "https://tiktok.com/@name",
        "hashtags": "#sport#fitness#outdoor",
        "trends": "summer fitness",
        "profile": "tiktok"
      }
    ]
  }
}

2.4 搜索标签和趋势

URL: /creators/search_tags/
方法: POST
描述: 专门用于搜索标签和趋势，会创建搜索会话并保存搜索结果

请求参数:

{
  "mode": "hashtag",        // 必填，搜索模式，"hashtag"或"trend"
  "keyword": "fitness",     // 必填，搜索关键词
  "profile": "tiktok"       // 可选，平台
}

响应数据:

{
  "code": 200,
  "message": "搜索hashtag成功，关键词: fitness",
  "data": {
    "id": 1,
    "session_number": 1,
    "creator_count": 8,
    "shoppable_creators": 5,
    "avg_followers": 13000.5,
    "avg_gmv": 6500.25,
    "avg_video_views": 22500.75,
    "date_created": "2023-06-01",
    "creators": [
      {
        "id": 1,
        "session": 1,
        "name": "创作者名称",
        "avatar": "https://example.com/avatar.jpg",
        "category": "Sports & Outdoor",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-2",
        "followers": 15000,
        "gmv": 8000,
        "items_sold": 500,
        "avg_video_views": 25000,
        "has_ecommerce": true,
        "tiktok_url": "https://tiktok.com/@name",
        "hashtags": "#sport#fitness#outdoor",
        "trends": "summer fitness",
        "profile": "tiktok"
      }
    ]
  }
}

2.5 自然语言搜索创作者

URL: /creators/search_individual/
方法: POST
描述: 根据用户输入的自然语言文本搜索达人，使用外部API进行处理

请求参数:

{
  "criteria": "我需要粉丝超过10万的健身类达人，擅长做运动装备测评", // 必填，搜索条件
  "top_n": 10                                         // 可选，返回结果数量，默认10
}

响应数据:

{
  "code": 200,
  "message": "搜索创作者成功",
  "data": {
    "id": 1,
    "session_number": 1,
    "creator_count": 10,
    "shoppable_creators": 7,
    "avg_followers": 150000.5,
    "avg_gmv": 9500.25,
    "avg_video_views": 35000.75,
    "date_created": "2023-06-01",
    "creators": [
      {
        "id": 1,
        "session": 1,
        "name": "创作者名称",
        "avatar": "https://example.com/avatar.jpg",
        "category": "Sports & Outdoor",
        "ecommerce_level": "L4",
        "exposure_level": "KOL-2",
        "followers": 180000,
        "gmv": 12000,
        "items_sold": 800,
        "avg_video_views": 45000,
        "has_ecommerce": true,
        "tiktok_url": "https://tiktok.com/@name",
        "hashtags": "#sport#fitness#outdoor#review",
        "trends": "fitness equipment review",
        "profile": "tiktok"
      }
    ]
  }
}

3. 字段说明

3.1 搜索会话字段

字段名	类型	说明
id	整数	会话ID
session_number	整数	会话编号
creator_count	整数	创作者数量
shoppable_creators	整数	可购物创作者数量
avg_followers	浮点数	平均粉丝数
avg_gmv	浮点数	平均GMV(商品总价值)
avg_video_views	浮点数	平均视频观看量
date_created	日期	创建日期

3.2 创作者字段

字段名	类型	说明
id	整数	创作者ID
session	整数	所属会话ID
name	字符串	创作者名称
avatar	URL	头像链接
category	字符串	类别，可选值：Phones & Electronics, Womenswear & Underwear等
ecommerce_level	字符串	电商等级，可选值：L1, L2, L3, L4, L5, New tag
exposure_level	字符串	曝光等级，可选值：KOC-1, KOC-2, KOL-2, KOL-3, New tag
followers	浮点数	粉丝数
gmv	浮点数	GMV(商品总价值)
items_sold	浮点数	已售项目数
avg_video_views	浮点数	平均视频观看量
has_ecommerce	布尔值	是否有电商
tiktok_url	URL	抖音链接
hashtags	字符串	标签，格式如"#sport#fitness"
trends	字符串	趋势，格式如"summer fitness"
profile	字符串	达人平台，可选值：tiktok, instagram, youtube, xiaohongshu, other

4. 使用示例

4.1 搜索标签为"fitness"的TikTok创作者

POST /api/creators/search_tags/
Content-Type: application/json
Authorization: Token your_token_here

{
  "mode": "hashtag",
  "keyword": "fitness",
  "profile": "tiktok"
}

4.2 获取最近一次搜索会话的详情

GET /api/sessions/1/
Authorization: Token your_token_here

4.3 使用自然语言搜索创作者

POST /api/creators/search_individual/
Content-Type: application/json
Authorization: Token your_token_here

{
  "criteria": "需要3个粉丝超过50万的美妆达人，产品转化率高",
  "top_n": 3
}

17 KiB Raw Blame History Unescape Escape

Discovery模块API文档

概述

通用响应格式

分页响应格式

认证方式

1. 搜索会话管理 (Sessions)

1.1 获取搜索会话列表

1.2 创建搜索会话

1.3 获取搜索会话详情

1.4 更新搜索会话

1.5 删除搜索会话

1.6 获取会话创作者列表

1.7 获取会话摘要

1.8 搜索会话

2. 创作者管理 (Creators)

2.1 获取创作者列表

2.2 获取创作者详情

2.3 搜索创作者

2.4 搜索标签和趋势

2.5 自然语言搜索创作者

3. 字段说明

3.1 搜索会话字段

3.2 创作者字段

4. 使用示例

4.1 搜索标签为"fitness"的TikTok创作者

4.2 获取最近一次搜索会话的详情

4.3 使用自然语言搜索创作者

17 KiB

Raw Blame History