6. 公开资源 API 6.2 获取偶像列表【基础探测通过，待数据联调】

Table of Contents

6.2 获取偶像列表【基础探测通过，待数据联调】

GET /tieup/api/v1/artists

查询参数：

参数 类型 必填 说明
keyword string 否 艺名、昵称、简介
artist_category_id integer 否 偶像类型 ID
artist_type integer 否 1=个人艺人，2=经纪公司艺人
city_code string 否 城市代码
follow_scope string 否 关注筛选：all=全部，followed=我关注的偶像；followed 需要登录态
page integer 否 页码，默认 1
page_size integer 否 每页数量，默认 20，最大 100

返回分页结构为 items + pagination，仅展示 tieup_user.status = 1、is_idol = 1、存在艺人档案，且存在 tieup_artist_pricing.status = 1 启用定价配置的数据。未创建定价记录或定价配置已禁用的艺人不进入列表；已保存启用配置但价格为 0，或提问、视频通话业务开关关闭的艺人仍可展示。该条件在分页前执行，因此 pagination.total 与过滤后的列表口径一致。返回项包含 is_followed，1 表示当前用户已关注，2 表示未关注；未登录查询全部列表时固定返回 2。follow_scope=followed 时必须携带有效 Authorization，未登录或 Token 无效返回 401。

卡片主媒体规则：featured_media_url 优先取艺人相册 album_media 中第一张图片；没有图片时取第一条视频；相册没有可用图片/视频时回退艺人头像。featured_media_type 用于区分 image、video、avatar；当主媒体是视频时，featured_media_cover_url 返回相册视频素材的封面/首帧图，其他场景为空字符串。

统计口径：follow_count 统计当前关注量；subscription_count 统计当前有效订阅量；received_candy_amount 统计提问、视频通话、福利兑换中粉丝实际消耗的糖果合计，不使用金额收入表折算。

响应字段：

字段 类型 说明
items array 当前页数据列表
items[].id integer 艺人 ID
items[].user_id integer 绑定的 APP 用户 ID
items[].artist_name string 艺人对外展示名称
items[].nickname string 用户昵称
items[].avatar string 艺人头像 URL，来源 tieup_artist.avatar
items[].featured_media_url string 卡片主媒体 URL：优先相册图片，其次相册视频，最后头像
items[].featured_media_type string 卡片主媒体类型：image、video、avatar
items[].featured_media_cover_url string 视频主媒体封面/首帧图 URL；非视频主媒体为空字符串
items[].album_media array 艺人相册素材列表
items[].album_media[].type string 素材类型：image 或 video
items[].album_media[].url string 素材 URL
items[].album_media[].cover_url string 视频封面 URL，仅视频素材返回
items[].album_media[].duration integer 视频时长，单位秒，仅视频素材返回
items[].intro_type string 短介绍类型：text、audio 或空字符串
items[].intro_text string 一句话文字介绍
items[].intro_audio_url string 一句话语音介绍 URL
items[].intro_audio_duration integer 语音介绍时长，单位秒
items[].personal_intro string 自我介绍
items[].gender integer 性别：0=未知，1=男，2=女
items[].artist_type integer 艺人类型：1=个人艺人，2=经纪公司艺人
items[].artist_category_id integer/null 艺人分类 ID
items[].category_name string 艺人分类名称
items[].artist_online_status integer 艺人身份在线状态：0=离线，1=在线；只根据 tieup_artist_{artist_id} 融云身份计算
items[].is_followed integer 当前用户是否已关注：1=已关注，2=未关注
items[].follow_count integer 关注量
items[].subscription_count integer 当前有效订阅量
items[].received_candy_amount string 收到糖果量，按粉丝实际消耗糖果合计
pagination object 分页信息
pagination.page integer 当前页码
pagination.page_size integer 每页数量
pagination.total integer 总数量
pagination.next_cursor null 下一页游标，页码分页时为空

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "items": [
      {
        "id": 20001,
        "user_id": 10001,
        "artist_name": "王心凌",
        "nickname": "甜心教主",
        "artist_online_status": 1,
        "avatar": "https://cdn.example.com/artist/avatar.png",
        "featured_media_url": "https://cdn.example.com/album/stage.png",
        "featured_media_type": "image",
        "featured_media_cover_url": "",
        "album_media": [
          {
            "type": "image",
            "url": "https://cdn.example.com/album/stage.png"
          },
          {
            "type": "video",
            "url": "https://cdn.example.com/album/intro.mp4",
            "cover_url": "https://cdn.example.com/album/intro-cover.png",
            "duration": 58
          }
        ],
        "intro_type": "audio",
        "intro_text": "",
        "intro_audio_url": "https://cdn.example.com/intro.m4a",
        "intro_audio_duration": 58,
        "personal_intro": "独立音乐人，用声音讲述故事。",
        "gender": 2,
        "artist_type": 1,
        "artist_category_id": 10,
        "category_name": "歌手",
        "is_followed": 1,
        "follow_count": 13000,
        "subscription_count": 155,
        "received_candy_amount": "82000.00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "next_cursor": null
    }
  }
}