OmniBox

Appearance

夸克网盘接口清单 ​

来源：backend/internal/drives/quark.go

1. 获取分享 Token ​

接口概览 ​

项目值
方法POST
URLhttps://drive-pc.quark.cn/1/clouddrive/share/sharepage/token?pr=ucpro&fr=pc
作用通过分享 ID 和提取码换取 stoken，后续列表/播放/转存接口都依赖该字段

请求体参数 ​

参数类型必填说明
pwd_idstring是分享链接 ID
passcodestring否提取码，无提取码时传空字符串

请求示例 ​

bash
curl --request POST \
  --url 'https://drive-pc.quark.cn/1/clouddrive/share/sharepage/token?pr=ucpro&fr=pc' \
  --data '{
    "passcode": "",
    "pwd_id": "44aff4afe805"
}'

响应示例 ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "timestamp": 1775135948,
  "data": {
    "subscribed": false,
    "stoken": "OGgzfRSgpHtSFtXVbVQO3fsK9+Bghj6lPRPMay7lQjA=",
    "share_type": 0,
    "author": {
      "member_type": "SUPER_VIP",
      "avatar_url": "http://image.quark.cn/o/uop/1Ht08/;;0,uop/g/uop/avatar/e0ef337919b3fca555e19f645753c3e0.jpg;3,160",
      "nick_name": "满足*火龙果"
    },
    "url_type": 1,
    "expired_type": 1,
    "expired_at": 4102416000000,
    "title": "罪人 (2025)"
  },
  "metadata": {
    "_t_group": "0:_s_vp:1",
    "_g_group": "4:_s_wl:1;0:_s_vp:1;2:_s_bp:1;3:_s_vtp:1;1:_s_ap:0"
  }
}

关键响应字段 ​

字段说明后续用途
statusHTTP 业务状态（200 成功）判断请求是否可继续
code业务码（0 成功）异常分支判断
data.stoken分享会话令牌调 sharepage/detail、save 等核心参数
data.title分享标题页面展示/日志记录
data.expired_at过期时间戳（毫秒）判断链接是否过期
data.author分享者信息展示和诊断

2. 获取分享详情/目录 ​

接口概览 ​

项目值
方法GET
URLhttps://drive-h.quark.cn/1/clouddrive/share/sharepage/detail
作用拉取分享目录内容（文件/文件夹列表），支持分页与排序，配合 stoken 访问受保护分享

Query 参数 ​

参数类型必填说明
_pagenumber是页码，从 1 开始
_sizenumber是每页数量，常用 100
_sortstring否排序规则，如 file_type:asc,file_name:asc
pdir_fidstring是父目录 FID，根目录一般传 0
pwd_idstring是分享链接 ID
stokenstring是由「获取分享 Token」接口返回的访问令牌
frstring否来源标识，常见 pc
prstring否产品标识，常见 ucpro
vernumber否接口版本，示例中为 2

请求示例 ​

bash
curl --request GET \
  --url 'https://drive-h.quark.cn/1/clouddrive/share/sharepage/detail?_page=1&_size=100&_sort=file_type:asc,file_name:asc&fr=pc&pdir_fid=0&pr=ucpro&pwd_id=9bbda01d2d73&stoken=+jfS6/DoLqcs/PZux1l2wPlAykZ/Dd36xSo3RYdQl+Y=&ver=2' \
  --header 'Accept: */*' \
  --header 'Cookie: <你的夸克Cookie>'

响应示例 ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "timestamp": 1775139062,
  "data": {
    "is_owner": 0,
    "list": [
      {
        "fid": "e2118391554e4f659fd57a90c17f2e65",
        "file_name": "请求救援 Send Help (2026)",
        "pdir_fid": "b0e64840b1fa42b39fdd795727244187",
        "file_type": 0,
        "size": 0,
        "include_items": 2,
        "share_fid_token": "65da33aa287a4571d09bec5e7a8076f2",
        "dir": true,
        "file": false,
        "created_at": 1774320052335,
        "updated_at": 1774337167672
      }
    ]
  },
  "metadata": {
    "_size": 100,
    "_page": 1,
    "_count": 1,
    "_total": 1
  }
}

响应示例（文件场景：非目录项） ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "timestamp": 1775139329,
  "data": {
    "is_owner": 0,
    "list": [
      {
        "fid": "bddc397a022941b18f523012344576c9",
        "file_name": "简中.srt",
        "pdir_fid": "e2118391554e4f659fd57a90c17f2e65",
        "category": 6,
        "file_type": 1,
        "size": 84526,
        "format_type": "text/plain",
        "share_fid_token": "277ac19ce65c50b22e9eb0d678ad8a01",
        "dir": false,
        "file": true
      },
      {
        "fid": "04c690fa08cf42e7b33079e99f40a6c1",
        "file_name": "Send.Help.2026.2160p.AMZN.WEB-DL.DDP5.1.DV.HDR.H.265.mkv",
        "pdir_fid": "e2118391554e4f659fd57a90c17f2e65",
        "category": 1,
        "file_type": 1,
        "size": 17418481737,
        "format_type": "video/x-matroska",
        "video_max_resolution": "4k",
        "video_width": 3840,
        "video_height": 1600,
        "fps": 24,
        "duration": 6812,
        "preview_url": "https://dl-c-zb-u.drive.quark.cn/.../preview?...",
        "share_fid_token": "e4e4d8fb68e9f5fd2cf0bb6dc552136b",
        "dolby_vision": true,
        "dir": false,
        "file": true
      }
    ]
  },
  "metadata": {
    "_size": 100,
    "_page": 1,
    "video_total": 1,
    "_count": 2,
    "_total": 2
  }
}

关键响应字段 ​

字段说明后续用途
data.list当前目录下的条目数组前端目录列表渲染
data.list[].fid文件/目录唯一标识进入子目录、播放、转存时使用
data.list[].share_fid_token分享文件 token调用保存/转存接口时必需
data.list[].dir / file是否目录/文件区分 UI 和后续操作类型
data.list[].include_items目录内条目数量（目录场景）展示目录统计信息
data.list[].category文件分类（如 1=视频、6=文档/文本）列表过滤与图标展示
data.list[].format_typeMIME 类型判断播放器/预览器类型
data.list[].duration媒体时长（秒）播放信息展示与断点续播
data.list[].video_width / video_height视频分辨率清晰度展示与策略选择
data.list[].video_max_resolution最大清晰度标签前端画质标记（如 4k）
data.list[].preview_url预览地址非正式播放预览或缩略图跳转
metadata._page / _size / _total分页信息翻页与总数展示
metadata.video_total当前页/条件下视频条目数视频统计展示

目录项与文件项差异 ​

字段目录项（dir=true）文件项（file=true）
file_type常见 0常见 1
size通常 0实际字节大小
include_items常见存在通常不存在
duration/video_*通常不存在视频文件常见存在
后续操作继续 pdir_fid=<目录fid> 拉子目录播放、转存、下载

使用说明 ​

  • 首次拉取根目录时 pdir_fid=0；进入子目录后改为目标目录的 fid。
  • 若返回空列表，先检查 pwd_id 与 stoken 是否匹配，stoken 过期后需重新调用「获取分享 Token」。
  • _sort=file_type:asc,file_name:asc 可使目录优先展示，且按文件名升序排列。
  • 对文件项务必保留 fid + share_fid_token，后续 save、play、download 链路都会用到这组映射。

3. 获取播放信息 ​

接口概览 ​

项目值
方法POST
URLhttps://drive.quark.cn/1/clouddrive/file/v2/play?pr=ucpro&fr=pc
作用根据文件 fid 获取可播放清晰度列表、转码地址、音轨能力和拖拽预览帧信息

请求体参数 ​

参数类型必填说明
fidstring是目标视频文件 FID
resolutionsstring否期望清晰度集合，逗号分隔（如 low,normal,high,super,2k,4k）
supportsstring否期望能力集合，逗号分隔（如 fmp4_av,m3u8,dolby_vision）

请求示例 ​

bash
curl --request POST \
  --url 'https://drive.quark.cn/1/clouddrive/file/v2/play?pr=ucpro&fr=pc' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的夸克Cookie>' \
  --data '{
    "fid": "c6eb65c1d08c48e19cd3bb048731c6c8",
    "resolutions": "low,normal,high,super,2k,4k",
    "supports": "fmp4_av,m3u8,dolby_vision"
  }'

响应示例（精简） ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "timestamp": 1775139629,
  "data": {
    "default_resolution": "super",
    "origin_default_resolution": "super",
    "video_list": [
      {
        "resolution": "4k",
        "right": "svip",
        "member_right": "svip",
        "trans_status": "success",
        "accessable": true,
        "supports_format": "mp4",
        "video_info": {
          "duration": 6811,
          "size": 4254058560,
          "format": "mp4",
          "width": 3840,
          "height": 1600,
          "bitrate": 4995,
          "codec": "h264",
          "fps": 24,
          "url": "https://video-play-m0-zb.drive.quark.cn/..."
        }
      },
      {
        "resolution": "low",
        "right": "normal",
        "member_right": "normal",
        "trans_status": "success",
        "accessable": true,
        "supports_format": "mp4",
        "video_info": {
          "duration": 6811,
          "size": 190504361,
          "format": "mp4",
          "width": 480,
          "height": 200,
          "bitrate": 223,
          "codec": "h264",
          "fps": 24,
          "url": "https://video-play-m0-zb.drive.quark.cn/..."
        }
      },
      {
        "resolution": "dolby_vision",
        "right": "svip",
        "member_right": "svip",
        "trans_status": "raw",
        "accessable": false,
        "supports_format": "Matroska / WebM;raw",
        "video_func_type": "DOLBY_VISION"
      }
    ],
    "audio_list": [
      {
        "type": "dolby_eac3",
        "right": "svip",
        "member_right": "svip",
        "accessable": false
      }
    ],
    "file_name": "Send.Help.2026.2160p.AMZN.WEB-DL.DDP5.1.DV.HDR.H.265.mkv",
    "size": 17418481737,
    "last_play_info": {
      "time": 0
    },
    "seek_preview_data": {
      "total_frame_count": 1135,
      "total_sprite_count": 38,
      "frame_width": 249,
      "frame_height": 140,
      "preview_sprite_infos": [
        {
          "url": "https://thumb-c-zb.drive.quark.cn/...",
          "frame_count": 30,
          "times": [6004, 12004, 18046]
        }
      ]
    },
    "meta": {
      "duration": 6812,
      "size": 17418481737,
      "format": "matroska,webm",
      "width": 3840,
      "height": 1600,
      "bitrate": 20456,
      "codec": "hevc",
      "fps": 24
    },
    "preload_level": 1,
    "has_seek_preview_data": true
  }
}

关键响应字段 ​

字段说明后续用途
data.default_resolution默认播放清晰度前端初始清晰度选择
data.video_list可用视频清晰度列表清晰度切换菜单
data.video_list[].resolution清晰度标识（low/high/super/4k 等）UI 展示与质量切换
data.video_list[].video_info.url该清晰度直链播放地址播放器实际播放源
data.video_list[].accessable当前账号是否可访问该清晰度可播/灰显控制
data.video_list[].right清晰度权限等级（normal/svip）会员能力判断
data.video_list[].trans_status转码状态（success/raw）过滤不可播放项
data.audio_list音轨能力列表音轨能力提示（如杜比）
data.last_play_info.time上次播放进度（秒）断点续播
data.seek_preview_data拖拽预览雪碧图数据时间轴预览图
data.meta源文件元数据（编码/分辨率/码率）信息面板展示
data.has_seek_preview_data是否存在拖拽预览数据前端是否启用预览能力

使用说明 ​

  • video_list 需优先过滤 accessable=true 且 trans_status=success 的条目作为可播放源。
  • 接口里字段名为 accessable（非 accessible），解析时建议兼容此拼写。
  • 高清（如 4k、dolby_vision）常伴随 svip 权限；普通账号应回退到 normal 可访问清晰度。
  • seek_preview_data.preview_sprite_infos[].times 为毫秒时间点，可直接映射播放器拖拽时间轴。
  • video_info.url 多为时效签名链接，过期后需重新调用本接口获取新地址。

4. 转存分享文件 ​

接口概览 ​

项目值
方法POST
URLhttps://drive-pc.quark.cn/1/clouddrive/share/sharepage/save?pr=ucpro&fr=pc
作用将分享链接中的文件转存到个人网盘指定目录，返回任务执行结果

请求体参数 ​

参数类型必填说明
fid_liststring[]是待转存的分享文件 FID 列表
fid_token_liststring[]是与 fid_list 一一对应的 share_fid_token
pwd_idstring是分享链接 ID
stokenstring是分享访问令牌（来自 token 接口）
to_pdir_fidstring是目标保存目录 FID
pdir_fidstring否源目录 FID（根目录可为空字符串）
scenestring否场景标记，示例为 link

请求示例 ​

bash
curl --request POST \
  --url 'https://drive-pc.quark.cn/1/clouddrive/share/sharepage/save?pr=ucpro&fr=pc' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的夸克Cookie>' \
  --data '{
    "fid_list": ["26ee2c93b46941d38bde971f0260b4ba"],
    "fid_token_list": ["97b7d3bab9d43c9a65e0838a39ec4ef8"],
    "pdir_fid": "",
    "pwd_id": "b8c29bce211c",
    "scene": "link",
    "stoken": "nk1nkZFp/PY5cNlpBpAkbrko2VcwnGWLhwb4ZzwVFnU=",
    "to_pdir_fid": "e616f1911f9747c08b0cd665b0a2fbf3"
  }'

响应示例 ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "timestamp": 1775140889,
  "data": {
    "task_id": "5246ca2cc9624e7c8429aceda32b6119",
    "task_sync": true,
    "task_resp": {
      "status": 200,
      "code": 0,
      "message": "ok",
      "timestamp": 1775140889,
      "data": {
        "task_id": "5246ca2cc9624e7c8429aceda32b6119",
        "event_id": "3bkby7-2956c893189825",
        "task_type": 17,
        "task_title": "分享-转存",
        "status": 1,
        "created_at": 1775140889177,
        "finished_at": 1775140889268,
        "save_as": {
          "save_as_select_top_fids": ["b9f7578fc6014ed28a2891ac159a9d68"],
          "save_as_top_fids": ["b9f7578fc6014ed28a2891ac159a9d68"],
          "save_as_sum_num": 1,
          "to_pdir_fid": "e616f1911f9747c08b0cd665b0a2fbf3",
          "to_pdir_name": "omnibox",
          "remain_capacity": 6425428130227,
          "min_save_file_size": 17697417369
        }
      }
    }
  },
  "metadata": {
    "tq_gap": 500
  }
}

关键响应字段 ​

字段说明后续用途
data.task_id转存任务 ID查询任务状态或日志关联
data.task_sync是否同步返回任务结果决定是否继续轮询 task 接口
data.task_resp.data.status任务执行状态（示例为 1）判定转存成功/失败
data.task_resp.data.save_as.save_as_top_fids转存后新文件 FID 列表后续播放、分享、发送会话消息
data.task_resp.data.save_as.to_pdir_fid实际保存目录 FID二次确认落盘目录
data.task_resp.data.save_as.remain_capacity转存后剩余容量（字节）空间告警与容量展示
metadata.tq_gap任务队列建议轮询间隔（毫秒）轮询节流控制

使用说明 ​

  • fid_list 与 fid_token_list 必须按索引严格对应，否则会出现参数合法但转存失败。
  • 转存前建议校验 to_pdir_fid 是否存在且有写权限，避免任务创建成功但落盘失败。
  • 当 task_sync=false 或未返回完整 task_resp 时，需走「查询转存任务状态」接口轮询。
  • save_as_top_fids 是后续播放链路最关键产物，建议第一时间持久化映射关系。

5. 查询转存任务状态 ​

接口概览 ​

项目值
方法GET
URLhttps://drive-pc.quark.cn/1/clouddrive/task
作用根据 task_id 查询转存任务最终状态与产物 FID

Query 参数 ​

参数类型必填说明
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc
task_idstring是转存任务 ID（来自 save 接口）
retry_indexnumber否轮询序号，初始可传 0

请求示例 ​

bash
curl --request GET \
  --url 'https://drive-pc.quark.cn/1/clouddrive/task?pr=ucpro&fr=pc&task_id=4a8f69291706478b803202aa2a2699e8&retry_index=0' \
  --header 'Cookie: <你的夸克Cookie>'

响应示例 ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "timestamp": 1775141743,
  "data": {
    "task_id": "4a8f69291706478b803202aa2a2699e8",
    "event_id": "97qacb-2956ce8976c056",
    "task_type": 17,
    "task_title": "分享-转存",
    "status": 2,
    "created_at": 1775141670676,
    "finished_at": 1775141671577,
    "save_as": {
      "search_exit": true,
      "save_as_select_top_fids": ["a3b4e961281641879e6273e069580288"],
      "save_as_top_fids": ["a3b4e961281641879e6273e069580288"],
      "save_as_sum_num": 1,
      "to_pdir_fid": "606a6c71e94d44d191f97c19fb528c73",
      "to_pdir_name": "omnibox",
      "remain_capacity": 1071616966721,
      "min_save_file_size": 25803056676
    }
  },
  "metadata": {
    "tq_gap": 500
  }
}

关键响应字段 ​

字段说明后续用途
data.status任务状态（示例 2）轮询终止条件判断
data.save_as.save_as_top_fids转存后文件 FID 列表进入下载/会话发送链路
data.save_as.to_pdir_fid / to_pdir_name实际落盘目录校验目标目录
data.save_as.remain_capacity当前剩余容量（字节）空间告警
data.finished_at完成时间戳（毫秒）任务耗时统计
metadata.tq_gap建议轮询间隔（毫秒）轮询节流

使用说明 ​

  • task_id 来自「转存分享文件」接口，二者必须成对使用。
  • 当返回终态后，优先取 save_as_top_fids 作为后续下载或发送会话的输入。
  • 若轮询频率过高，按 metadata.tq_gap 退避可减少限流风险。

6. 获取会员状态 ​

接口概览 ​

项目值
方法GET
URLhttps://drive-pc.quark.cn/1/clouddrive/member
作用获取账号会员等级、容量、权益余量、身份信息，用于判断转存/播放/下载权限

Query 参数 ​

参数类型必填说明
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc
uc_param_strstring否预留参数，可为空
fetch_subscribeboolean否是否返回订阅相关信息，常见 true
_chstring否场景渠道，常见 home
fetch_identityboolean否是否返回身份信息，常见 true

请求示例 ​

bash
curl --request GET \
  --url 'https://drive-pc.quark.cn/1/clouddrive/member?pr=ucpro&fr=pc&uc_param_str=&fetch_subscribe=true&_ch=home&fetch_identity=true' \
  --header 'Cookie: <你的夸克Cookie>'

响应示例 ​

json
{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775140114,
  "data": {
    "member_type": "EXP_SVIP",
    "exp_svip_exp_at": 1794412800000,
    "exp_at": 1794412800000,
    "total_capacity": 6597069766656,
    "use_capacity": 140005961408,
    "secret_total_capacity": 6597069766656,
    "secret_use_capacity": 140005961408,
    "member_info": {
      "video_save_to_uses": 0,
      "video_save_to_remains": 3,
      "file_save_to_remains": 200,
      "offline_download_remains": 1
    },
    "member_status": {
      "VIP": "UNPAID",
      "MINI_VIP": "UNPAID",
      "Z_VIP": "UNPAID",
      "SUPER_VIP": "UNPAID"
    },
    "identity": [
      {
        "user_identity_type": 4,
        "status": 1,
        "expire_time": 1794393312235
      }
    ]
  },
  "metadata": {
    "range_size": 10485760,
    "server_cur_time": 1775140114969
  }
}

关键响应字段 ​

字段说明后续用途
data.member_type当前会员类型（如 EXP_SVIP）判断可用清晰度、下载/转存权益
data.exp_at / exp_svip_exp_at会员到期时间（毫秒）会员有效期提示与降级兜底
data.member_info.video_save_to_remains视频转存剩余额度转存前预校验
data.member_info.file_save_to_remains文件转存剩余额度批量转存限额控制
data.member_info.offline_download_remains离线下载剩余次数下载任务前判断
data.total_capacity / use_capacity总容量/已用容量空间展示与写入前校验
data.member_status各会员等级支付状态前端权益页展示
data.identity账号身份标签数组特殊活动身份或权益判定
metadata.server_cur_time服务端当前时间本地时钟校准、到期判定

使用说明 ​

  • 播放链路中出现 svip 清晰度时，建议先读取 member_type 与 member_info 做可用性判断和提示。
  • 会员到期判断建议使用服务端时间 metadata.server_cur_time 对齐，避免本地时间误差。
  • message 可能为空字符串，成功建议以 status=200 && code=0 为准。

7. 批量发送会话消息（转存链路） ​

接口概览 ​

项目值
方法POST
URLhttps://drive-social-api.quark.cn/1/clouddrive/chat/conv/msg/batch_send?pr=ucpro&fr=pc&sys=win32
作用将网盘文件作为会话消息批量发送到指定会话，产出社交会话消息与文件上下文

Query 参数 ​

参数类型必填说明
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc
sysstring否客户端系统标识，示例 win32

请求体参数 ​

参数类型必填说明
conversationsobject[]是会话发送任务数组
conversations[].conversation_idstring是目标会话 ID
conversations[].conversation_typenumber是会话类型（示例 3）
conversations[].file_listobject[]是待发送文件列表
conversations[].file_list[].fidstring是网盘文件 FID
conversations[].file_list[].client_extra.local_msg_idstring否客户端本地消息 ID（幂等/回显）
conversations[].merge_filenumber否是否合并发送，示例 0
return_msg_as_listnumber否返回消息列表开关，示例 1

请求示例 ​

bash
curl --request POST \
  --url 'https://drive-social-api.quark.cn/1/clouddrive/chat/conv/msg/batch_send?pr=ucpro&fr=pc&sys=win32' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的夸克Cookie>' \
  --data '{
    "conversations": [
      {
        "conversation_id": "300000103982583563",
        "conversation_type": 3,
        "file_list": [
          {
            "client_extra": {
              "local_msg_id": "b9b42b73-132e-4c71-ad88-e78cb8cc15a5"
            },
            "fid": "4dfce82ddd0449feb1e196232f89e7e3"
          }
        ],
        "merge_file": 0
      }
    ],
    "return_msg_as_list": 1
  }'

响应示例（精简） ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "req_id": "35ju79-2956c99bfbf276",
  "timestamp": 1775141024,
  "data": {
    "send_msg_list": [
      {
        "store_msg_id": "1775141024832000",
        "conversation_id": "300000103531356710",
        "conversation_type": 3,
        "msg_type": 30003,
        "content": "Send.Help.2026.2160p.AMZN.WEB-DL.DV.HDR10+.mp4",
        "extra": {
          "custom_extra": {
            "file": {
              "fid": "4dfce82ddd0449feb1e196232f89e7e3",
              "file_name": "Send.Help.2026.2160p.AMZN.WEB-DL.DV.HDR10+.mp4",
              "size": 17697417369,
              "format_type": "video/mp4",
              "duration": 6812,
              "video_width": 3840,
              "video_height": 1600,
              "thumbnail": "https://drive-social-api.quark.cn/1/clouddrive/chat/conv/file/thumbnail?...",
              "preview_url": "https://drive-social-api.quark.cn/1/clouddrive/chat/conv/file/preview?..."
            },
            "local_msg_id": "b9b42b73-132e-4c71-ad88-e78cb8cc15a5"
          }
        }
      }
    ],
    "conversations": [
      {
        "conversation_id": "300000103982583563",
        "conversation_type": 3,
        "file_list": [
          {
            "fid": "4dfce82ddd0449feb1e196232f89e7e3",
            "send_result": {
              "code": 0,
              "store_msg_id": "1775141024832000"
            }
          }
        ]
      }
    ]
  }
}

关键响应字段 ​

字段说明后续用途
data.send_msg_list服务端落库后的消息列表会话页实时渲染
data.send_msg_list[].store_msg_id消息唯一 ID消息去重、下载 token 关联
data.send_msg_list[].msg_type消息类型（示例 30003 文件消息）不同消息卡片渲染
data.send_msg_list[].extra.custom_extra.file文件详细元数据文件卡片展示、预览入口
...file.thumbnail/preview_url会话域名下预览地址会话内预览与封面显示
data.conversations[].file_list[].send_result.code单文件发送结果码批量发送逐条成功判定
data.conversations[].file_list[].send_result.store_msg_id单文件对应消息 ID回填本地消息映射
req_id请求追踪 ID问题排查与日志关联

使用说明 ​

  • 一个请求可包含多个会话和多个文件，建议以 send_result.code 做逐项结果确认。
  • local_msg_id 建议由客户端生成并回填，用于本地占位消息与服务端消息对齐。
  • 会话文件预览链接多带临时令牌参数，过期后需重新走会话文件 token 流程获取。
  • 接口响应里的 conversation_id 可能出现与请求不同的会话上下文，业务侧以 send_result 与 store_msg_id 为最终落库依据更稳妥。

8. 获取会话文件下载 Token ​

接口概览 ​

项目值
方法POST
URLhttps://drive-social-api.quark.cn/1/clouddrive/chat/conv/file/acquire_dl_token?pr=ucpro&fr=pc&sys=win32
作用基于会话消息获取会话域下载 token，供会话文件下载或预览链路使用

Query 参数 ​

参数类型必填说明
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc
sysstring否客户端系统标识，示例 win32

请求体参数 ​

参数类型必填说明
conversation_idstring是会话 ID
conversation_typenumber是会话类型（示例 3）
msg_idstring是会话消息 ID（store_msg_id）

请求示例 ​

bash
curl --request POST \
  --url 'https://drive-social-api.quark.cn/1/clouddrive/chat/conv/file/acquire_dl_token?pr=ucpro&fr=pc&sys=win32' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的夸克Cookie>' \
  --data '{
    "conversation_id": "300000103982583563",
    "conversation_type": 3,
    "msg_id": "1775141672405000"
  }'

响应示例 ​

json
{
  "status": 200,
  "code": 0,
  "message": "ok",
  "req_id": "986kfu-2956d04a150e58",
  "timestamp": 1775141900,
  "data": {
    "token": "c50e32ece6d744fd9a9643a41cd1ec4b",
    "expired_timestamp": 1782917900334
  }
}

关键响应字段 ​

字段说明后续用途
data.token会话文件下载令牌会话文件下载/预览接口鉴权
data.expired_timestamptoken 到期时间（毫秒）过期重取策略
req_id请求追踪 ID故障排查

使用说明 ​

  • msg_id 建议直接使用 batch_send 返回的 store_msg_id，避免消息上下文不匹配。
  • token 有有效期，下载失败时先校验是否过期再重试。

9. 获取下载地址 ​

接口概览 ​

项目值
方法POST
URLhttps://drive-pc.quark.cn/1/clouddrive/file/download?pr=ucpro&fr=pc&sys=win32
作用根据网盘文件 FID 获取直链下载地址及刷新 token

Query 参数 ​

参数类型必填说明
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc
sysstring否客户端系统标识，示例 win32

请求体参数 ​

参数类型必填说明
fidsstring[]是待获取下载地址的文件 FID 列表
tokenstring否下载 token（部分场景必传）
ab_tagstring否A/B 标记，示例 _
cn_swstring否开关标识，示例 open

请求示例 ​

bash
curl --request POST \
  --url 'https://drive-pc.quark.cn/1/clouddrive/file/download?pr=ucpro&fr=pc&sys=win32' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的夸克Cookie>' \
  --data '{
    "ab_tag": "_",
    "cn_sw": "open",
    "fids": ["a3b4e961281641879e6273e069580288"],
    "token": "b0d7e42a213646b7bf21bea232a58ca8"
  }'

响应示例（精简） ​

json
{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775142029,
  "data": [
    {
      "fid": "a3b4e961281641879e6273e069580288",
      "file_name": "Sinners (2025) - 2160p WEB-DL HDR10+ H265 DDP 5.1 Atmos.mkv",
      "size": 25803056676,
      "format_type": "video/x-matroska",
      "obj_key": "3ce20630a7984da9854adf228c9cc4e1",
      "download_url": "https://dl-c-zb-cf.pds.quark.cn/...signature...",
      "preview_url": "https://drive-pc.quark.cn/1/clouddrive/file/video/preview?fid=...",
      "video_max_resolution": "4k",
      "md5": "7b76041727e01225b8cd4f9bb78f7739",
      "range_size": 10485760,
      "duration": 8258,
      "video_width": 3840,
      "video_height": 2160,
      "risk_type": 1,
      "file": true
    }
  ],
  "metadata": {
    "refresh_token": "b0d7e42a213646b7bf21bea232a58ca8",
    "refresh_token_expired_timestamp": 1837349672467,
    "acc1": "MA==",
    "acc2": "MA=="
  }
}

关键响应字段 ​

字段说明后续用途
data[].download_url文件下载直链（含签名参数）直接下载或流式转发
data[].fid / file_name文件标识与名称下载任务展示
data[].range_size建议分片大小（字节）断点续传分块策略
data[].md5文件摘要完整性校验
data[].video_* / duration视频元数据播放前信息展示
metadata.refresh_token刷新 token后续下载地址续签
metadata.refresh_token_expired_timestamp刷新 token 到期时间token 更新策略

使用说明 ​

  • download_url 为签名时效链接，过期后需使用刷新 token 或重新请求本接口。
  • 建议结合 range_size 做分段下载，降低单连接失败影响。
  • 当接口返回多个文件时，按 fid 映射结果，避免文件名重复导致错配。

备用方式：分享直下（不经转存） ​

在 backend/internal/drives/quark.go 的 getDownloadURLViaShareDirect() 中，还实现了一种“分享直下”调用 file/download 的方式：直接使用分享上下文参数换取 download_url。

适用场景 ​

  • 已有分享链路参数（pwd_id、stoken、fid、fidsToken）；
  • 目标是快速获取直链，不希望先执行“转存到我的网盘”。

请求 URL ​

POST https://drive-pc.quark.cn/1/clouddrive/file/download?pr=ucpro&fr=pc

入参说明（对应 getDownloadURLViaShareDirect(pwdID, stoken, fid, fidsToken, config)） ​

方法入参请求体字段类型必填说明
pwdIDpwd_idstring是分享链接 ID
stokenstokenstring是分享访问令牌（由分享 token 接口获取）
fidfids[0]string是分享条目 FID
fidsTokenfids_token[0]string是与 FID 对应的分享文件 token（通常来自 sharepage/detail 的 share_fid_token）
-speedup_sessionstring否代码中固定传空字符串 \"\"
config.CookieHeader Cookiestring是账号 Cookie（用于鉴权）

请求体示例 ​

json
{
  "fids": ["<fid>"],
  "fids_token": ["<fidsToken>"],
  "pwd_id": "<pwdID>",
  "stoken": "<stoken>",
  "speedup_session": ""
}

返回处理说明（代码行为） ​

  • 代码会校验外层 status == 200；
  • 从 data[0].download_url 提取直链；
  • 封装 DownloadInfo 返回，并附带请求头（Cookie、Referer、User-Agent）供后续下载代理使用。

注意事项 ​

  • fids_token 与 fids 必须一一对应，否则容易出现“参数合法但无下载地址”的情况。
  • stoken 和 share_fid_token 都有时效，失效时需重新走分享 token + detail 流程。
  • 该模式依赖分享权限，若分享失效/被取消，则无法继续获取 download_url。

10. 文件排序/查询 ​

接口概览 ​

项目值
方法GET
URLhttps://drive-pc.quark.cn/1/clouddrive/file/sort
作用获取网盘目录列表，支持分页和多字段排序（目录/文件混合返回）

Query 参数 ​

参数类型必填说明
_pagenumber是页码，从 1 开始
_sizenumber是每页数量
_sortstring否排序规则，如 file_type:asc,updated_at:desc
pdir_fidstring是目录 FID，根目录传 0
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc

请求示例 ​

bash
curl --request GET \
  --url 'https://drive-pc.quark.cn/1/clouddrive/file/sort?_page=1&_size=200&_sort=file_type:asc,updated_at:desc&fr=pc&pdir_fid=0&pr=ucpro' \
  --header 'Cookie: <你的夸克Cookie>'

响应示例（精简） ​

json
{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775140193,
  "data": {
    "last_view_list": [],
    "recent_file_list": [],
    "list": [
      {
        "fid": "e616f1911f9747c08b0cd665b0a2fbf3",
        "file_name": "omnibox",
        "pdir_fid": "0",
        "file_type": 0,
        "include_items": 1,
        "sort_type": "file_type:asc,file_name:asc",
        "dir": true,
        "file": false,
        "created_at": 1773793344792,
        "updated_at": 1775139979116
      },
      {
        "fid": "d4a92c114ebc4505add2a00643d2b844",
        "file_name": "D.e.ad.2025.1080p.中英字幕.404.mp4",
        "pdir_fid": "0",
        "category": 1,
        "file_type": 1,
        "size": 2605110724,
        "format_type": "video/mp4",
        "video_max_resolution": "super",
        "video_width": 1920,
        "video_height": 800,
        "duration": 4929,
        "thumbnail": "https://drive-pc.quark.cn/1/clouddrive/file/video/thumbnail?fid=...",
        "preview_url": "https://drive-pc.quark.cn/1/clouddrive/file/video/preview?fid=...",
        "dir": false,
        "file": true
      }
    ]
  },
  "metadata": {
    "_size": 200,
    "_page": 1,
    "_count": 9,
    "_total": 0
  }
}

关键响应字段 ​

字段说明后续用途
data.list目录下文件/目录混合列表文件管理页渲染
data.list[].fid文件或目录唯一标识进入目录、播放、删除等操作主键
data.list[].dir / file条目类型标记区分目录跳转与文件操作
data.list[].include_items目录项子条目数目录统计展示
data.list[].sort_type当前条目排序策略回显排序状态展示/调试
data.list[].save_as_source是否来自转存来源标记展示与策略区分
data.list[].video_max_resolution视频最大清晰度播放能力预估
data.list[].preview_url / thumbnail预览与缩略图地址列表封面展示
metadata._page / _size / _count分页信息翻页与数量显示

使用说明 ​

  • 常用排序：file_type:asc,file_name:asc（目录优先）或 file_type:asc,updated_at:desc（目录优先+最近更新靠前）。
  • 根目录查询传 pdir_fid=0，子目录查询传目标目录 fid。
  • metadata._total 可能返回 0（未计算总量场景），分页建议优先依据 list 长度和 _count。
  • 当列表包含视频文件时，可直接复用 fid 调用「获取播放信息」接口。

11. 删除文件 ​

接口概览 ​

项目值
方法POST
URLhttps://drive-pc.quark.cn/1/clouddrive/file/delete?pr=ucpro&fr=pc
作用批量删除网盘中的文件或目录（FID 列表）

Query 参数 ​

参数类型必填说明
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc

请求体参数 ​

参数类型必填说明
action_typenumber是操作类型；项目内删除使用 2
fileliststring[]是待删除的 fid 列表
exclude_fidsstring[]否排除不删的 fid，无则传空数组 []

请求示例 ​

bash
curl --request POST \
  --url 'https://drive-pc.quark.cn/1/clouddrive/file/delete?pr=ucpro&fr=pc' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的夸克Cookie>' \
  --data '{
    "action_type": 2,
    "exclude_fids": [],
    "filelist": ["6a24811abe314a66b9a7716a128dc459"]
  }'

响应示例（失败：目标已不存在） ​

当文件已被删除或不存在时，可能返回业务错误（HTTP 仍为 200 或 400，以实际为准；以下为你抓包示例）：

json
{
  "status": 400,
  "code": 23004,
  "message": "[文件已经删除,请稍后重试]",
  "req_id": "37go7a-2956d91b2ff750",
  "timestamp": 1775143056
}

关键响应字段 ​

字段说明后续用途
status / code外层状态与业务码成功为 200 + 0；失败时 code 如 23004
message错误说明对用户提示或日志
req_id请求追踪 ID排障

使用说明 ​

  • 成功时一般为 status=200 且 code=0（具体 data 结构以抓包为准）。
  • 重复删除同一 fid 可能得到 23004 等码，业务上应视为幂等（已删除即达成目标）。
  • 批量删除时注意 filelist 长度与接口限制；失败条目可结合 req_id 与单条重试策略处理。

12. 创建目录 ​

接口概览 ​

项目值
方法POST
URLhttps://drive-pc.quark.cn/1/clouddrive/file?pr=ucpro&fr=pc
作用在指定父目录下创建新文件夹

Query 参数 ​

参数类型必填说明
prstring否产品标识，常见 ucpro
frstring否来源标识，常见 pc

请求体参数 ​

参数类型必填说明
pdir_fidstring是父目录 FID，根目录为 0
file_namestring是新目录名称
dir_pathstring否目录路径，根下创建常传空字符串 ""
dir_init_lockboolean否目录初始化锁，示例为 false

请求示例 ​

bash
curl --request POST \
  --url 'https://drive-pc.quark.cn/1/clouddrive/file?pr=ucpro&fr=pc' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的夸克Cookie>' \
  --data '{"dir_init_lock":false,"dir_path":"","file_name":"omnibox","pdir_fid":"0"}'

响应示例 ​

json
{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775142517,
  "data": {
    "finish": true,
    "fid": "abdf8d9d9d4d4a138c67c2286bf1f58a"
  },
  "metadata": {}
}

关键响应字段 ​

字段说明后续用途
data.finish是否创建完成异步场景下可用于轮询（本例为同步完成）
data.fid新建目录的 FID作为转存目标 to_pdir_fid、后续列表 pdir_fid

使用说明 ​

  • 与 backend/internal/drives/quark.go 中 createSaveDir 一致：pdir_fid=0、dir_path=""、dir_init_lock=false 即在根目录创建指定名称文件夹。
  • 同名目录是否允许重复创建以服务端策略为准；失败时根据 code/message 处理或先 file/sort 查重。
  • 创建成功后应持久化 data.fid，供保存、列表等接口使用。

13. 项目实际调用流程图（quark.go） ​

本节按当前 backend/internal/drives/quark.go 的实现补充，便于理解“文档接口”在项目中的真实串联方式。

13.1 播放主链路（GetVideoPlayInfo） ​

13.2 转存与任务轮询链路（getOrSaveFileFid） ​

13.3 下载双路径（转存下载 vs 分享直下） ​

13.4 保存目录生命周期（createSaveDir / clearSaveDir） ​

13.5 对接建议 ​

  • 播放场景优先走“转存后下载”路径，稳定性和权限一致性更好。
  • 若已有 pwd_id + stoken + share_fid_token 且希望减少步骤，可走“分享直下”。
  • 任务型接口（save、task）建议统一按 tq_gap 做轮询节流。
  • 目录操作（创建/清空）建议统一封装，避免不同链路重复处理 saveDirId 状态。

Copyright © 2024 OmniBox