25 KiB
25 KiB
达人详情模块 (daren_detail) API 接口文档
模块简介
daren_detail
模块是达人管理系统的核心模块,提供了完整的达人信息管理功能,包括:
- 达人筛选、详情查看、信息更新
- 营销活动管理和达人合作详情
- 多维度指标数据管理(协作指标、视频指标、直播指标、粉丝统计、趋势分析)
- 视频内容管理
- 公有达人库和私有达人库管理
认证方式
所有接口都需要使用 CustomTokenAuthentication
进行身份验证,请在请求头中包含:
Authorization: Token <your_token>
1. 达人管理相关接口
1.1 添加/更新达人
- 接口路径:
POST /creators/add/
- 功能: 添加新达人或更新现有达人信息
- 请求方法: POST
请求体参数:
{
"name": "达人姓名", // 必填
"avatar_url": "头像URL",
"category": "Beauty & Personal Care",
"e_commerce_level": "L3", // 或数字3
"exposure_level": "KOL-1",
"followers": 125000,
"gmv": "$534.1k", // 或数字534.1
"items_sold": "2.5k", // 或数字2.5
"avg_video_views": "85k", // 或数字85000
"pricing": {
"individual": 200, // 或直接传数字
"package": "套餐描述"
},
"collab_count": 15,
"latest_collab": "2024-03-15",
"e_commerce_platforms": ["TikTok Shop", "Instagram Shop"],
"mcn": "MCN机构名称"
}
响应格式:
{
"code": 200,
"message": "达人信息已添加/更新",
"data": {
"created": true, // true为新建,false为更新
"creator_id": 123
}
}
1.2 获取达人详情
- 接口路径:
GET /creators/{creator_id}/
- 功能: 获取指定达人的详细信息
- 请求方法: GET
URL参数:
creator_id
: 达人ID(必填)
响应格式:
{
"code": 200,
"message": "获取成功",
"data": {
"creator": {
"id": 123,
"name": "达人姓名",
"avatar": "头像URL",
"email": "邮箱",
"social_user": {
"instagram": "@name",
"tiktok": "tiktok链接"
},
"location": "地理位置",
"live_schedule": "直播时间安排"
},
"metrics": {
"e_commerce_level": "L3",
"exposure_level": "KOL-1",
"followers": "125k",
"actual_followers": 125000,
"gmv": "$534k",
"actual_gmv": 534.1,
"items_sold": "2500",
"avg_video_views": "85k",
"actual_views": 85000,
"gpm": "$2.35", // 每千次观看收入
"gmv_per_customer": "$213.64" // 每位客户GMV
},
"business": {
"category": "Beauty & Personal Care",
"categories": ["Beauty & Personal Care"],
"mcn": "MCN机构",
"pricing": {
"price": "$200",
"package": "套餐描述"
},
"collab_count": 15,
"latest_collab": "2024-03-15",
"e_commerce_platforms": ["TikTok Shop"]
},
"analytics": {
"gmv_by_channel": {...}, // 按渠道分析
"gmv_by_category": {...} // 按类别分析
}
}
}
1.3 更新达人详细信息
- 接口路径:
POST /creators/update_detail/
- 功能: 更新达人的详细信息(联系方式、社交账号等)
- 请求方法: POST
请求体参数:
{
"creator_id": 123, // 必填
"email": "新邮箱",
"instagram": "@new_name",
"tiktok_link": "新TikTok链接",
"location": "新地理位置",
"live_schedule": "新直播时间安排",
"mcn": "新MCN机构",
"gmv_by_channel": {...}, // 按渠道GMV分析数据
"gmv_by_category": {...} // 按类别GMV分析数据
}
响应格式:
{
"code": 200,
"message": "达人详细信息已更新",
"data": {
"creator_id": 123,
"name": "达人姓名"
}
}
1.4 获取达人品牌合作详情
- 接口路径:
GET /creators/{creator_id}/campaigns/
- 功能: 获取指定达人与各品牌的合作活动详情,支持分页
- 请求方法: GET
URL参数:
creator_id
: 达人ID(必填)page
: 页码,默认为1page_size
: 每页数量,默认为10
响应格式:
{
"code": 200,
"message": "获取成功",
"data": [
{
"brand": {
"id": "U",
"name": "品牌名称",
"color": "#E74694"
},
"pricing_detail": "$80",
"start_date": "05/31/2024",
"end_date": "05/29/2024",
"status": "completed", // pending, in_progress, completed, cancelled
"gmv_achieved": "$120",
"views_achieved": "650",
"video_link": "视频链接",
"campaign_id": 456,
"campaign_name": "活动名称"
}
],
"pagination": {
"current_page": 1,
"total_pages": 5,
"total_count": 45,
"has_next": true,
"has_prev": false
},
"creator": {
"id": 123,
"name": "达人姓名",
"avatar": "头像URL",
"category": "Beauty & Personal Care",
"exposure_level": "KOL-1"
}
}
2. 营销活动相关接口
2.1 获取营销活动列表
- 接口路径:
GET /campaigns/
- 功能: 获取所有活跃的营销活动列表
- 请求方法: GET
响应格式:
{
"code": 200,
"message": "获取成功",
"data": [
{
"id": 456,
"name": "品牌名 产品名",
"brand": "品牌名",
"product": "产品名"
}
]
}
2.2 添加达人到营销活动
- 接口路径:
POST /campaigns/add/
- 功能: 将达人添加到指定营销活动中
- 请求方法: POST
请求体参数:
{
"campaign_id": 456, // 必填
"creator_ids": [123, 124, 125] // 达人ID列表,必填
}
响应格式:
{
"code": 200,
"message": "成功添加达人到活动",
"data": {
"campaign": {
"id": "456",
"name": "活动名称"
},
"added_creators": [
{
"id": 123,
"name": "达人姓名"
}
],
"stats": {
"added": 1, // 成功添加数量
"skipped": 0, // 跳过数量(达人不存在)
"already_exists": 2 // 已存在数量
}
}
}
3. 指标数据相关接口
3.1 获取创作者指标数据
- 接口路径:
GET /creators/{creator_id}/metrics/
- 功能: 获取创作者的协作指标、视频和直播指标数据
- 请求方法: GET
URL参数:
creator_id
: 创作者ID(必填)start_date
: 开始日期,格式:YYYY-MM-DD(可选)end_date
: 结束日期,格式:YYYY-MM-DD(可选)
响应格式:
{
"code": 200,
"message": "获取成功",
"data": {
"collaboration_metrics": {
"avg_commission_rate": "15.5%",
"products_count": 25,
"brand_collaborations": 8,
"product_price": "$50 - $200",
"date_range": "Mar 01, 2024 - Mar 31, 2024"
},
"video": {
"gpm": "$2.35",
"videos_count": 12,
"avg_views": "85k",
"avg_engagement": "3.2%",
"avg_likes": 2500,
"date_range": "Mar 01, 2024 - Mar 31, 2024"
},
"shoppable_video": {
"gpm": "$3.15",
"videos_count": 8,
"avg_views": "92k",
"avg_engagement": "4.1%",
"avg_likes": 3200,
"date_range": "Mar 01, 2024 - Mar 31, 2024"
},
"live": {
"gpm": "$4.50",
"lives_count": 5,
"avg_views": "150k",
"avg_engagement": "5.8%",
"avg_likes": 8500,
"date_range": "Mar 01, 2024 - Mar 31, 2024"
},
"shoppable_live": {
"gpm": "$6.20",
"lives_count": 3,
"avg_views": "180k",
"avg_engagement": "7.2%",
"avg_likes": 12000,
"date_range": "Mar 01, 2024 - Mar 31, 2024"
}
}
}
3.2 更新创作者指标数据
- 接口路径:
POST /creators/metrics/update/
- 功能: 更新创作者的指标数据
- 请求方法: POST
请求体参数:
{
"creator_id": 123, // 必填
"metrics_type": "collaboration", // 必填:collaboration, video, shoppable_video, live, shoppable_live
"metrics_data": {
"start_date": "2024-03-01", // 必填,格式:YYYY-MM-DD
"end_date": "2024-03-31", // 必填,格式:YYYY-MM-DD
// 根据metrics_type不同,以下参数有所不同:
// 当metrics_type为"collaboration"时:
"avg_commission_rate": "15.5%", // 或数字15.5
"products_count": 25,
"brand_collaborations": 8,
"product_price": "$50 - $200", // 格式:$最小值 - $最大值
// 当metrics_type为"video"或"shoppable_video"时:
"gpm": "$2.35", // 或数字2.35
"videos_count": 12,
"avg_views": "85k", // 或数字85000
"avg_engagement": "3.2%", // 或数字3.2
"avg_likes": 2500,
// 当metrics_type为"live"或"shoppable_live"时:
"gpm": "$4.50",
"lives_count": 5,
"avg_views": "150k",
"avg_engagement": "5.8%",
"avg_likes": 8500
}
}
响应格式:
{
"code": 200,
"message": "协作指标数据已更新", // 根据metrics_type变化
"data": {
"created": true, // true为新建,false为更新
"metrics_id": 789
}
}
3.3 获取创作者粉丝统计数据
- 接口路径:
GET /creator/{creator_id}/followers/
或GET /creator/followers/?creator_id={creator_id}
- 功能: 获取创作者的粉丝性别、年龄、地域分布统计
- 请求方法: GET
URL参数:
creator_id
: 创作者ID(必填)
响应格式:
{
"code": 200,
"message": "获取成功",
"data": {
"gender": {
"female": 65.5,
"male": 34.5
},
"age": {
"18-24": 25.2,
"25-34": 35.8,
"35-44": 22.1,
"45-54": 12.3,
"55+": 4.6
},
"locations": {
"TX": 18.5,
"FL": 15.2,
"NY": 12.8,
"CA": 11.3,
"GE": 8.9
},
"date_range": {
"start_date": "2024-03-29",
"end_date": "2024-04-28"
}
}
}
3.4 更新创作者粉丝统计数据
- 接口路径:
POST /creator/followers/update/
- 功能: 更新创作者的粉丝统计数据
- 请求方法: POST
请求体参数:
{
"creator_id": 123, // 必填
"follower_data": {
"date_range": {
"start_date": "2024-03-29", // 必填
"end_date": "2024-04-28" // 必填
},
"gender": {
"female": 65.5,
"male": 34.5
},
"age": {
"18-24": 25.2,
"25-34": 35.8,
"35-44": 22.1,
"45-54": 12.3,
"55+": 4.6
},
"locations": {
"TX": 18.5,
"FL": 15.2,
"NY": 12.8,
"CA": 11.3,
"GE": 8.9
}
}
}
响应格式:
{
"code": 200,
"message": "粉丝统计数据已更新",
"data": {
"created": true,
"metrics_id": 890
}
}
3.5 获取创作者趋势数据
- 接口路径:
GET /creator/{creator_id}/trends/
或GET /creator/trends/?creator_id={creator_id}
- 功能: 获取创作者的GMV、销量、粉丝、观看量等趋势数据
- 请求方法: GET
URL参数:
creator_id
: 创作者ID(必填)start_date
: 开始日期,格式:YYYY-MM-DD(可选,默认最近30天)end_date
: 结束日期,格式:YYYY-MM-DD(可选,默认今天)
响应格式:
{
"code": 200,
"message": "获取成功",
"data": {
"gmv": [1250.5, 1380.2, 1156.8, ...], // 30天的GMV数据
"items_sold": [850, 920, 780, ...], // 30天的销量数据
"followers": [125000, 125150, 125300, ...], // 30天的粉丝数据
"video_views": [85000, 92000, 78000, ...], // 30天的观看量数据
"engagement_rate": [3.2, 3.5, 2.8, ...], // 30天的互动率数据
"dates": ["2024-03-01", "2024-03-02", ...], // 对应的日期
"date_range": {
"start_date": "2024-03-01",
"end_date": "2024-03-31"
}
}
}
3.6 更新创作者趋势数据
- 接口路径:
POST /creator/trend/update/
- 功能: 更新单日的创作者趋势数据
- 请求方法: POST
请求体参数:
{
"creator_id": 123, // 必填
"date": "2024-03-15", // 必填,格式:YYYY-MM-DD
"metrics": {
"gmv": 1250.5,
"items_sold": 850,
"followers": 125000,
"video_views": 85000,
"engagement_rate": 3.2
}
}
响应格式:
{
"code": 200,
"message": "趋势数据已更新",
"data": {
"created": true,
"metrics_id": 901,
"date": "2024-03-15"
}
}
4. 视频管理相关接口
4.1 获取创作者视频列表
- 接口路径:
GET /creator/{creator_id}/videos/
或GET /creator/videos/?creator_id={creator_id}
- 功能: 获取创作者的视频列表,分为普通视频和带产品视频
- 请求方法: GET
URL参数:
creator_id
: 创作者ID(必填)page
: 页码,默认为1page_size
: 每页数量,默认为6
响应格式:
{
"code": 200,
"message": "获取成功",
"data": {
"regular_videos": {
"videos": [
{
"id": 1,
"title": "视频标题",
"thumbnail_url": "缩略图URL",
"badge": "red", // red, gold等
"view_count": 2130,
"like_count": 20,
"release_date": "2025-03-31"
}
],
"total": 15,
"page": 1,
"page_size": 6,
"total_pages": 3
},
"product_videos": {
"videos": [
{
"id": 4,
"title": "带产品的视频标题",
"thumbnail_url": "缩略图URL",
"badge": "red",
"view_count": 2130,
"like_count": 20,
"release_date": "2025-03-31",
"has_product": true,
"product_name": "产品名称",
"product_url": "产品链接"
}
],
"total": 8,
"page": 1,
"page_size": 6,
"total_pages": 2
}
}
}
4.2 添加创作者视频
- 接口路径:
POST /creator/video/add/
- 功能: 为创作者添加新视频
- 请求方法: POST
请求体参数:
{
"creator_id": 123, // 必填
"title": "视频标题", // 必填
"release_date": "2024-03-15", // 必填,格式:YYYY-MM-DD
"video_type": "regular", // 可选:regular, product,默认regular
"description": "视频描述",
"thumbnail_url": "缩略图URL",
"video_url": "视频URL",
"video_id": "vid_123456", // 可选,不提供会自动生成
"badge": "red", // 可选:red, gold等,默认red
"view_count": 2130,
"like_count": 20,
"comment_count": 5,
"has_product": false, // 如果video_type为product,会自动设为true
"product_name": "产品名称", // 有产品时填写
"product_url": "产品链接" // 有产品时填写
}
响应格式:
{
"code": 200,
"message": "视频添加成功",
"data": {
"video_id": 456,
"created": true // true为新建,false为更新
}
}
5. 公有达人库相关接口
5.1 获取公有达人库列表
- 接口路径:
GET /public/creators/
- 功能: 获取公有达人库中的达人列表
- 请求方法: GET
URL参数:
page
: 页码,默认为1page_size
: 每页数量,默认为10category
: 分类过滤(可选)keyword
: 关键词搜索(可选)
响应格式:
{
"code": 200,
"message": "获取成功",
"data": [
{
"public_id": 123,
"creator_id": 456,
"name": "达人姓名",
"avatar": "头像URL",
"category": "Beauty & Personal Care",
"e_commerce_level": "L3",
"exposure_level": "KOL-1",
"followers": "125k",
"gmv": "$534k",
"avg_video_views": "85k",
"pricing": "$200",
"pricing_package": "套餐描述",
"collab_count": 15,
"remark": "公有库备注",
"category_public": "公有库分类"
}
],
"pagination": {
"current_page": 1,
"total_pages": 15,
"total_count": 150,
"has_next": true,
"has_prev": false
}
}
5.2 筛选公有达人库
- 接口路径:
POST /public/creators/filter/
- 功能: 根据过滤条件筛选公有达人库中的达人
- 请求方法: POST
URL参数:
page
: 页码,默认为1page_size
: 每页数量,默认为10
请求体参数:
{
"filter": {
"category": ["Beauty & Personal Care"], // 多选
"e_commerce_level": ["L1", "L2", "L3"], // 多选
"exposure_level": ["KOL-1", "KOC-1"], // 多选
"gmv_range": ["$0-$5k", "$5k-$25k"], // 多选
"views_range": ["10k-100k"], // 单选
"pricing": ["100-500"] // 单选
}
}
响应格式: 同5.1
5.3 添加达人到公有库
- 接口路径:
POST /public/creators/add/
- 功能: 将达人添加到公有达人库
- 请求方法: POST
请求体参数:
{
"creator_id": 456, // 必填
"category": "分类", // 可选
"remark": "备注信息" // 可选
}
响应格式:
{
"code": 200,
"message": "成功添加达人到公有库", // 或"成功更新达人到公有库"
"data": {
"creator": {
"id": 456,
"name": "达人姓名"
},
"public_pool": {
"id": 123,
"category": "分类",
"remark": "备注信息"
}
}
}
5.4 从公有库移除达人
- 接口路径:
POST /public/creators/remove/
- 功能: 从公有达人库中移除达人,同时更新私有库中相关记录的状态
- 请求方法: POST
请求体参数:
{
"creator_id": 456, // 二选一
"public_id": 123 // 二选一
}
响应格式:
{
"code": 200,
"message": "成功从公有库移除达人",
"data": {
"creator": {
"id": 456,
"name": "达人姓名"
},
"removed_from_public": true,
"updated_private_relations": 3,
"note": "已更新 3 个私有库中的相关记录状态"
}
}
6. 私有达人库相关接口
6.1 获取私有达人库列表
- 接口路径:
GET /private/pools/
- 功能: 获取当前用户的私有达人库列表
- 请求方法: GET
URL参数:
user_id
: 用户ID(可选,只能查看自己的)
响应格式:
{
"code": 200,
"message": "获取成功",
"data": [
{
"id": 123,
"name": "我的收藏",
"description": "私有库描述",
"is_default": true,
"creator_count": 25,
"created_at": "2024-03-15"
}
]
}
6.2 创建私有达人库
- 接口路径:
POST /private/pools/create/
- 功能: 创建新的私有达人库
- 请求方法: POST
请求体参数:
{
"name": "私有库名称", // 必填
"description": "私有库描述", // 可选
"is_default": false // 可选,是否设为默认库
}
响应格式:
{
"code": 200,
"message": "私有库创建成功",
"data": {
"id": 123,
"name": "私有库名称",
"is_default": false,
"creator_count": 0,
"created_at": "2024-03-15"
}
}
6.3 获取私有库中的达人
- 接口路径:
GET /private/pools/creators/{pool_id}/
或GET /private/pools/creators/?pool_id={pool_id}
- 功能: 获取指定私有库中的达人列表
- 请求方法: GET
URL参数:
pool_id
: 私有库ID(必填)page
: 页码,默认为1page_size
: 每页数量,默认为10status
: 状态过滤,默认为active(可选:active, archived, public_removed)keyword
: 关键词搜索(可选)
响应格式:
{
"code": 200,
"message": "获取成功",
"data": [
{
"relation_id": 789,
"creator_id": 456,
"name": "达人姓名",
"avatar": "头像URL",
"category": "Beauty & Personal Care",
"e_commerce_level": "L3",
"exposure_level": "KOL-1",
"followers": "125k",
"gmv": "$534k",
"avg_video_views": "85k",
"pricing": "$200",
"collab_count": 15,
"notes": "私有库备注",
"status": "active", // active, archived, public_removed
"added_from_public": true,
"added_at": "2024-03-15",
"is_public_removed": false,
"status_note": null
}
],
"pagination": {
"current_page": 1,
"total_pages": 3,
"total_count": 25,
"has_next": true,
"has_prev": false
},
"pool_info": {
"id": 123,
"name": "我的收藏",
"description": "私有库描述",
"is_default": true,
"user_id": 1,
"created_at": "2024-03-15"
}
}
6.4 添加达人到私有库
- 接口路径:
POST /private/pools/creators/add/
- 功能: 将达人添加到指定私有库
- 请求方法: POST
请求体参数:
{
"pool_id": 123, // 必填
"creator_id": 456, // 单个添加时使用
"creator_ids": [456, 457, 458], // 批量添加时使用
"notes": "备注信息" // 可选
}
响应格式:
{
"code": 200,
"message": "操作成功",
"data": {
"added": [
{
"id": 456,
"name": "达人姓名",
"action": "添加"
}
],
"already_exists_count": 2,
"pool": {
"id": 123,
"name": "我的收藏"
}
}
}
6.5 更新私有库中的达人
- 接口路径:
POST /private/pools/creators/update/
- 功能: 更新私有库中达人的状态或备注
- 请求方法: POST
请求体参数:
{
"relation_id": 789, // 必填
"status": "archived", // 可选:active, archived
"notes": "新的备注信息" // 可选,传null可清空
}
响应格式:
{
"code": 200,
"message": "更新成功",
"data": {
"relation_id": 789,
"creator_id": 456,
"pool_id": 123,
"status": "archived",
"notes": "新的备注信息"
}
}
6.6 从私有库移除达人
- 接口路径:
POST /private/pools/creators/remove/
- 功能: 从私有库中移除达人
- 请求方法: POST
请求体参数:
{
// 方式1:通过关联ID删除
"relation_id": 789, // 单个删除
"relation_ids": [789, 790], // 批量删除
// 方式2:通过私有库ID和达人ID删除
"pool_id": 123,
"creator_id": 456, // 单个删除
"creator_ids": [456, 457] // 批量删除
}
响应格式:
{
"code": 200,
"message": "移除成功",
"data": {
"deleted_count": 2,
"relation_ids": [789, 790], // 或creator_ids
"pool_id": 123
}
}
6.7 筛选私有库中的达人
- 接口路径:
POST /private/pools/creators/filter/
- 功能: 根据过滤条件筛选私有库中的达人
- 请求方法: POST
URL参数:
page
: 页码,默认为1page_size
: 每页数量,默认为10
请求体参数:
{
"pool_id": 123, // 必填
"filter": {
"status": "active", // 可选:active, archived, public_removed
"category": ["Beauty & Personal Care"], // 多选
"e_commerce_level": ["L1", "L2", "L3"], // 多选
"exposure_level": ["KOL-1", "KOC-1"], // 多选
"gmv_range": ["$0-$5k", "$5k-$25k"], // 多选
"views_range": ["10k-100k"], // 单选
"pricing": ["100-500"] // 单选
}
}
响应格式: 同6.3
错误响应格式
所有接口在出错时都会返回统一的错误格式:
{
"code": 400, // 错误状态码
"message": "错误描述信息",
"data": null
}
常见错误码:
400
: 请求参数错误401
: 用户未认证403
: 权限不足404
: 资源不存在409
: 资源冲突(如重名)500
: 服务器内部错误
使用示例
筛选达人示例
curl -X POST "https://api.example.com/creators/filter/?page=1" \
-H "Authorization: Token your_token_here" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"category": ["Beauty & Personal Care"],
"e_commerce_level": ["L2", "L3"],
"gmv_range": ["$5k-$25k", "$25k-$50k"]
}
}'
获取达人详情示例
curl -X GET "https://api.example.com/creators/123/" \
-H "Authorization: Token your_token_here"
更新指标数据示例
curl -X POST "https://api.example.com/creators/metrics/update/" \
-H "Authorization: Token your_token_here" \
-H "Content-Type: application/json" \
-d '{
"creator_id": 123,
"metrics_type": "video",
"metrics_data": {
"start_date": "2024-03-01",
"end_date": "2024-03-31",
"gpm": 2.35,
"videos_count": 12,
"avg_views": 85000,
"avg_engagement": 3.2,
"avg_likes": 2500
}
}'