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 启用定价配置并已选择订阅档位（subscription_plan_code 非空）的数据。未创建定价记录、定价配置已禁用或未选择订阅档位的艺人不进入列表；已保存启用配置并选择订阅档位，但价格为 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 的真实统计值为全历史订阅粉丝人数，按 artist_id + fan_user_id 去重，同一粉丝多次订阅或续订只计 1 人，生效中、已过期、已取消和已退款订阅均计入。列表查询完成后，艺人 ID 3/7/2/4/5/1/6/8 的 follow_count 会在真实统计值上分别叠加 11632/8526/6885/4675/1383/1132/962/678，并从上海时区 2026-08-25 起每经过一个自然日再叠加 50；同一组艺人的 subscription_count 会在真实统计值上分别叠加 8469/6830/5265/3542/1056/855/752/543，每经过一个自然日再叠加 30。基准日当天不叠加每日增量，早于基准日不产生负增量，其他艺人不叠加展示值。该展示处理发生在排序和分页之后，不改变列表顺序或分页结果。received_candy_amount 统计提问/追问、视频通话、历史福利兑换实际产生的消费扣糖流水绝对值，只统计 tieup_user_transaction.change_type = 2 的真实扣糖，后续退款属于独立正向流水且不冲减历史收到量，未产生扣糖流水的取消业务不计。列表排序使用累计消费金额：订阅按实际支付金额累计，iOS 使用订阅记录中的 iOS 实付价格快照，其他平台优先使用订单实际支付金额并在缺失时回退订阅金额快照；糖果支付按当前请求渠道生效的 candy_cash_exchange_rate 折算为人民币分后与订阅金额相加。本接口默认依次按累计消费金额 DESC、settled_at DESC、id DESC 排序，所有排序均在分页前执行。

响应字段：

字段 类型 说明
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 粉丝端仅返回审核状态为 passed 的相册素材，不返回 media_id/status
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.online_status，由艺人身份融云回调更新
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
    }
  }
}