J/daren
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
daren/discovery.md
jlj bca9490fba 添加单个单人简易信息
2025-05-23 20:35:52 +08:00

8.6 KiB
Raw Permalink Blame History

Discovery 模块 API 文档

本文档详细说明了 Discovery 模块的 API 接口，包括请求方法、URL、参数说明和响应格式。

目录

  1. 通用说明
  2. 创作者搜索会话接口
  3. 创作者发现接口

通用说明

基础URL

所有 API 的基础 URL 为：http://127.0.0.1:8000/api/discovery/

认证方式

所有 API 都需要 Token 认证。请在请求头中添加：

Authorization: Token <your_token>

响应格式

所有 API 返回的数据格式统一为：

{
  "code": 200,        // 状态码，200表示成功，其他表示错误
  "message": "成功",   // 状态描述
  "data": {}          // 返回的数据，可能是对象、数组或null
}

分页

列表接口支持分页，默认每页 20 条数据，最大每页 100 条。

分页参数：

  • page: 页码，从1开始
  • page_size: 每页数量，默认20

分页响应格式：

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

创作者搜索会话接口

搜索会话是指用户进行的一次创作者搜索，包含搜索结果和相关统计信息。

获取搜索会话列表

  • URL: /sessions/
  • 方法: GET
  • 描述: 获取所有搜索会话的列表
  • 参数:
    • 分页参数，参见分页部分
  • 响应示例: 
    {
  "code": 200,
  "message": "获取搜索会话列表成功",
  "data": [
    {
      "id": 1,
      "session_number": 123,
      "creator_count": 100,
      "shoppable_creators": 26,
      "avg_followers": 162.2,
      "avg_gmv": 534.1,
      "avg_video_views": 1.9,
      "date_created": "2023-01-01"
    }
  ]
}

获取搜索会话详情

  • URL: /sessions/{session_id}/
  • 方法: GET
  • 描述: 获取指定ID的搜索会话详细信息，包含搜索到的创作者列表
  • 参数:
    • session_id: 会话ID (路径参数)
  • 响应示例: 
    {
  "code": 200,
  "message": "获取搜索会话详情成功",
  "data": {
    "id": 1,
    "session_number": 123,
    "creator_count": 100,
    "shoppable_creators": 26,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2023-01-01",
    "creators": [
      // 创作者列表，见创作者数据结构
    ]
  }
}

创建搜索会话

  • URL: /sessions/
  • 方法: POST
  • 描述: 创建新的搜索会话
  • 请求参数: 
    {
  "session_number": 123,
  "creator_count": 100,
  "shoppable_creators": 26,
  "avg_followers": 162.2,
  "avg_gmv": 534.1,
  "avg_video_views": 1.9,
  "date_created": "2023-01-01"
}
  • 响应示例: 
    {
  "code": 200,
  "message": "创建搜索会话成功",
  "data": {
    "id": 1,
    "session_number": 123,
    "creator_count": 100,
    "shoppable_creators": 26,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2023-01-01"
  }
}

更新搜索会话

  • URL: /sessions/{session_id}/
  • 方法: PUT/PATCH
  • 描述: 更新搜索会话信息
  • 参数:
    • session_id: 会话ID (路径参数)
    • 请求体包含要更新的字段
  • 响应示例: 
    {
  "code": 200,
  "message": "更新搜索会话成功",
  "data": {
    // 更新后的会话信息
  }
}

删除搜索会话

  • URL: /sessions/{session_id}/
  • 方法: DELETE
  • 描述: 删除搜索会话
  • 参数:
    • session_id: 会话ID (路径参数)
  • 响应示例: 
    {
  "code": 200,
  "message": "删除搜索会话成功",
  "data": null
}

获取会话创作者列表

  • URL: /sessions/{session_id}/results/
  • 方法: GET
  • 描述: 获取指定会话的搜索结果（创作者列表）
  • 参数:
    • session_id: 会话ID (路径参数)
    • 分页参数，参见分页部分
  • 响应示例: 
    {
  "code": 200,
  "message": "获取会话创作者列表成功",
  "data": [
    // 创作者列表，见创作者数据结构
  ]
}

创作者发现接口

获取创作者列表

  • URL: /creators/
  • 方法: GET
  • 描述: 获取所有创作者的列表
  • 参数:
    • 分页参数，参见分页部分
  • 响应示例: 
    {
  "code": 200,
  "message": "获取创作者列表成功",
  "data": [
    {
      "id": 1,
      "name": "创作者名称",
      "avatar": "头像URL",
      "category": "Phones & Electronics",
      "ecommerce_level": "L2",
      "exposure_level": "KOC-1",
      "followers": 162.2,
      "gmv": 534.1,
      "items_sold": 18.1,
      "avg_video_views": 1.9,
      "has_ecommerce": true,
      "tiktok_url": "抖音链接",
      "session": 1
    }
  ]
}

获取创作者详情

  • URL: /creators/{creator_id}/
  • 方法: GET
  • 描述: 获取指定ID的创作者详细信息
  • 参数:
    • creator_id: 创作者ID (路径参数)
  • 响应示例: 
    {
  "code": 200,
  "message": "获取创作者详情成功",
  "data": {
    "id": 1,
    "name": "创作者名称",
    "avatar": "头像URL",
    "category": "Phones & Electronics",
    "ecommerce_level": "L2",
    "exposure_level": "KOC-1",
    "followers": 162.2,
    "gmv": 534.1,
    "items_sold": 18.1,
    "avg_video_views": 1.9,
    "has_ecommerce": true,
    "tiktok_url": "抖音链接",
    "session": 1
  }
}

搜索创作者

  • URL: /creators/search/
  • 方法: POST
  • 描述: 根据条件搜索创作者并创建新的搜索会话
  • 请求参数: 
    {
  "query": "搜索关键词",
  "category": "Phones & Electronics",  // 可选，见类别列表
  "ecommerce_level": "L2",            // 可选，见电商等级列表
  "exposure_level": "KOC-1"           // 可选，见曝光等级列表
}
  • 响应示例: 
    {
  "code": 200,
  "message": "搜索创作者成功",
  "data": {
    "id": 1,
    "session_number": 123,
    "creator_count": 5,
    "shoppable_creators": 3,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2023-01-01",
    "creators": [
      // 创作者列表，见创作者数据结构
    ]
  }
}

数据结构

创作者类别

  • Phones & Electronics: 手机与电子产品
  • Womenswear & Underwear: 女装与内衣
  • Sports & Outdoor: 运动与户外
  • Food & Beverage: 食品与饮料
  • Health: 健康
  • Kitchenware: 厨具
  • Furniture: 家具
  • Shoes: 鞋类
  • Home Supplies: 家居用品

电商等级

  • L1: Level 1
  • L2: Level 2
  • L3: Level 3
  • L4: Level 4
  • L5: Level 5
  • New tag: 新标签

曝光等级

  • KOC-1: Key Opinion Consumer 1级
  • KOC-2: Key Opinion Consumer 2级
  • KOL-2: Key Opinion Leader 2级
  • KOL-3: Key Opinion Leader 3级
  • New tag: 新标签

创作者数据结构

{
  "id": 1,
  "name": "创作者名称",
  "avatar": "头像URL",
  "category": "Phones & Electronics",
  "ecommerce_level": "L2",
  "exposure_level": "KOC-1",
  "followers": 162.2,       // 单位：K (千)
  "gmv": 534.1,             // 单位：K (千)
  "items_sold": 18.1,        // 单位：K (千)
  "avg_video_views": 1.9,    // 单位：M (百万)
  "has_ecommerce": true,     // 是否有电商能力
  "tiktok_url": "抖音链接",
  "session": 1               // 所属搜索会话ID
}

搜索会话数据结构

{
  "id": 1,
  "session_number": 123,      // 会话编号
  "creator_count": 100,       // 创作者数量
  "shoppable_creators": 26,   // 可购物创作者数量
  "avg_followers": 162.2,     // 平均粉丝数 (K)
  "avg_gmv": 534.1,           // 平均GMV (K)
  "avg_video_views": 1.9,     // 平均视频观看量 (M)
  "date_created": "2023-01-01" // 创建日期
}