UC 网盘接口清单

建议优先：配置 Open API access_token / refresh_token（下文 UC Open API：access_token / refresh_token 获取）后，uc.go 可走 getDownloadByToken + GET open-api-drive.uc.cn/file，播放链路更贴近官方 TV 客户端；浏览器 Cookie（pc-api.uc.cn）为另一条登录态，二者可并存，按业务选择。
来源：backend/internal/drives/uc.go、backend/internal/handlers/qr_auth/quark_uc.go
域名：open-api-drive.uc.cn（OAuth / 开放播放）、pc-api.uc.cn（Web 网盘 JSON API）。Web 侧常见 Query：pr=UCBrowser、fr=pc，部分 POST 附带 sys、ve。

对应代码：backend/internal/handlers/qr_auth/quark_uc.go（GetQrCode / GetCookie 的 type=uc 分支）。
用途：这条链路拿到的是 Web Cookie 登录态（供 pc-api.uc.cn 接口使用），与后面的 Open API token 链路独立。

整体流程：

getTokenForQrcodeLogin 获取扫码会话 token（用于生成二维码）。
轮询 getServiceTicketByQrcodeToken，成功后拿到 service_ticket。
请求 https://drive.uc.cn/account/info?st=<service_ticket>，拿用户信息并接收首批 Set-Cookie。
携带上一步 Cookie 再请求 https://pc-api.uc.cn/1/clouddrive/config?...，补齐/续签 Cookie，最终合并为可用登录态。

获取扫码会话 Token（生成二维码前置）

接口概览

项目	值
方法	`GET`
URL	`https://api.open.uc.cn/cas/ajax/getTokenForQrcodeLogin`
作用	返回 `data.members.token`，用于拼接扫码二维码 URL

Query 参数

参数	必填	说明
`client_id`	是	固定 `381`（UC）
`v`	是	固定 `1.2`
`request_id`	是	毫秒时间戳

请求示例

bash

curl --request GET \
  --url "https://api.open.uc.cn/cas/ajax/getTokenForQrcodeLogin?client_id=381&v=1.2&request_id=1775198958719" \
  --header "Referer: https://drive.uc.cn" \
  --header "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) UCBrowser/15.0.0 Chrome/100.0.4896.160 Safari/537.36"

说明（与项目实现一致）

项目 GetQrCode 会将该 token 组装到 UC 扫码 URL：https://su.uc.cn/1_n0ZCv?...&token=<token>&client_id=381...，然后返回二维码图片（Base64）与 query_token。
对外路由：GET /api/quark-uc-qr/qr?type=uc。

扫码后轮询换取 `service_ticket`

接口概览

项目	值
方法	`GET`
URL	`https://api.open.uc.cn/cas/ajax/getServiceTicketByQrcodeToken`
作用	用户扫码并确认后，返回 `service_ticket`

请求示例

bash

curl --location --request GET "https://api.open.uc.cn/cas/ajax/getServiceTicketByQrcodeToken?token=sta2c6333a2s8qr1gsspcfr97ptsxm3u&__t=1775198958719&client_id=381&v=1.2&request_id=1775198958719" \
  --header "Referer: https://drive.uc.cn" \
  --header "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) UCBrowser/15.0.0 Chrome/100.0.4896.160 Safari/537.36"

响应示例（成功）

json

{
  "status": 2000000,
  "message": "ok",
  "data": {
    "members": {
      "service_ticket": "sta2c63338e8zozwox0nvnvkuiws6xz2"
    }
  }
}

状态说明（项目轮询逻辑）

`status`	含义
`2000000`	扫码确认成功，可取 `data.members.service_ticket`
`50004001`	用户尚未确认，继续轮询
`50004002`	二维码失效/过期，需重新获取二维码

使用 `service_ticket` 获取用户信息与首批 Cookie

接口概览

项目	值
方法	`GET`
URL	`https://drive.uc.cn/account/info?st=<service_ticket>`
作用	验证票据、返回用户信息，并通过响应头下发首批 `Set-Cookie`

请求示例

bash

curl --location --request GET "https://drive.uc.cn/account/info?st=sta2c63338e8zozwox0nvnvkuiws6xz2" \
  --header "Referer: https://drive.uc.cn" \
  --header "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) UCBrowser/15.0.0 Chrome/100.0.4896.160 Safari/537.36"

响应示例（业务体）

json

{
  "success": true,
  "data": {
    "nickname": "UC网盘用户",
    "avatarUri": "",
    "uid": 100571526681,
    "mobilekps": "AATryhV/4436E5IyxPWAEmpFHgtQ0N59A6mher0hrFZYdst6I8DDLfk/3WeNsiBXwE+kQOYNR06GHYchuBGLc0mwk/aq/5T1YX6bxFjWKwNC3w==",
    "kps": "AARjSEJZ9AvL71enpQintUxe",
    "config": {}
  },
  "code": "OK"
}

关键点

Cookie 不在 JSON 体里，而在响应头 Set-Cookie。
需把 Set-Cookie 里的关键 cookie 名值提取后拼成 Cookie 字符串，供下一步 pc-api 请求继续使用。

接口概览

项目	值
方法	`GET`
URL	`https://pc-api.uc.cn/1/clouddrive/config?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6`
作用	使用上一步 Cookie 做一次配置请求，补齐并更新 `Set-Cookie`，得到最终可用 UC 网盘 Cookie

请求说明

请求头需带 Cookie: <上一步提取的 Cookie>。
读取本次响应 Set-Cookie 并合并覆盖同名项，得到最终 Cookie 串。
项目里 GetCookie 就是按这个顺序做合并，最后返回给前端或写入配置。

2. UC Open API：access_token / refresh_token 获取

面向 TV / 开放客户端的 OAuth 授权码模式：GET /oauth/authorize 拿二维码 → 手机 UC 扫码确认 → GET /oauth/code 轮询拿 code → POST .../ucdrive/token 换 access_token（及 refresh_token）。项目封装：GetUcTokenQrCode、GetUcTokenStatus（quark_uc.go）；消费：getDownloadByToken（uc.go）。

获取授权二维码 `GET /oauth/authorize`

用于生成电视端授权二维码；手机 UC 扫描后在端内确认，后续用同一 query_token 轮询 /oauth/code。

接口概览

项目	值
方法	`GET`
URL	`https://open-api-drive.uc.cn/oauth/authorize`
作用	返回 PNG 二维码的 Base64（`qr_data`）及轮询用 `query_token`

必选请求头（签名）

头	说明
`X-Pan-Client-Id`	与 Query `client_id` 一致（项目内固定值见 `quark_uc.go`）
`X-Pan-Tm`	毫秒时间戳字符串；与生成 `req_id`、签名时使用同一时间基准
`X-Pan-Token`	接口签名，见下文「签名算法」

Query 参数（与项目构造一致）

参数	说明
`req_id`	请求关联 ID；项目内为 `MD5(device_id + X-Pan-Tm)` 取十六进制前 16 字符
`client_id`	开放平台应用 ID
`scope`	示例 `netdisk`
`auth_type`	`code`（授权码模式）
`qrcode`	`1` 表示要返回二维码数据
`qr_width` / `qr_height`	如 `460`
`platform`	示例 `tv`
`app_ver`	客户端版本，如 `1.6.8`
`device_id` / `device_brand` / `device_name` / `device_model` / `build_device` / `build_product` / `device_gpu`	设备指纹，需与后续 `/oauth/code`、`/token` 请求保持一致
`channel`	示例 `UCTVOFFICIALWEB`
`activity_rect`	示例 `{}`，需 URL 编码

签名算法（`X-Pan-Token`）

与 quark_uc.go 中 generateXPanToken 一致：

text

plain = <METHOD> + "&" + <pathname> + "&" + <X-Pan-Tm> + "&" + <signKey>
X-Pan-Token = 小写十六进制( SHA256(plain) )

METHOD：本接口为 GET
pathname：本接口为 /oauth/authorize
signKey：与 client_id 配套，由开放平台下发，实现里硬编码于 GetUcTokenQrCode，勿泄露

请求示例（结构示意）

bash

curl --request GET \
  --url 'https://open-api-drive.uc.cn/oauth/authorize?req_id=<req_id>&app_ver=1.6.8&device_id=<device_id>&device_brand=Xiaomi&platform=tv&device_name=M2004J7AC&device_model=M2004J7AC&build_device=M2004J7AC&build_product=M2004J7AC&device_gpu=Adreno+%28TM%29+550&activity_rect=%7B%7D&channel=UCTVOFFICIALWEB&auth_type=code&client_id=<client_id>&scope=netdisk&qrcode=1&qr_width=460&qr_height=460' \
  --header 'X-Pan-Client-Id: <client_id>' \
  --header 'X-Pan-Tm: <毫秒时间戳>' \
  --header 'X-Pan-Token: <签名>'

响应示例（成功）

status: 0 表示成功；qr_data 为 PNG 的 Base64（解码即可渲染二维码）。

json

{
  "status": 0,
  "req_id": "01c3d93e21db0e37",
  "qr_data": "iVBORw0KGgoAAAANSUhEUgAAAcwAAAHM...（Base64 PNG，略）",
  "query_token": "sta2c633399k5404mtn4mkzc4xm99x9w"
}

字段	说明
`query_token`	下一步 `/oauth/code` 必填；与手机端会话绑定
`req_id`	与请求参数中的 `req_id` 对应，便于排障

查询扫码结果 `GET /oauth/code`

用手机扫描上节二维码并完成授权前后，用同一套设备参数 + query_token 轮询本接口；每次请求需重新生成 req_id 与 X-Pan-Tm / X-Pan-Token（pathname 为 /oauth/code）。

接口概览

项目	值
方法	`GET`
URL	`https://open-api-drive.uc.cn/oauth/code`
作用	未就绪返回等待或业务 `errno`；成功时 `status: 0` 且返回短期有效的 `code`，用于换 `access_token`

请求示例（结构示意）

bash

curl --request GET \
  --url 'https://open-api-drive.uc.cn/oauth/code?req_id=<新req_id>&app_ver=1.6.8&device_id=<device_id>&...&client_id=<client_id>&scope=netdisk&query_token=<上一步query_token>' \
  --header 'X-Pan-Client-Id: <client_id>' \
  --header 'X-Pan-Tm: <新时间戳>' \
  --header 'X-Pan-Token: <对/oauth/code的签名>'

响应示例（二维码过期）

json

{
  "status": -1,
  "errno": 11002,
  "error_info": "授权码Code二维码过期",
  "req_id": "c7e82a7988d3b7df"
}

`status` / `errno` 与项目映射（`GetUcTokenStatus`）

外层 `status`	`errno`（若有）	含义	项目内抽象
`0`	—	已拿到 `code`，可换 token	继续请求 `/token`
`400`	—	等待用户扫码	`NEW`
`-1`	`11003`	已扫码，待手机确认授权	`SCANED`
`-1`	`11002`	二维码/会话过期	`EXPIRED`，需重新走 authorize

成功且 status == 0 时，响应中常见根级字段 code（字符串）；若嵌套在 data 内，实现中亦做了兼容解析。

用 `code` 换取 `access_token` + `refresh_token`：`POST /token`

当前后端与抓包一致时使用：

项目	值
方法	`POST`
URL	`http://api.extscreen.com/ucdrive/token`
`Content-Type`	`application/json`

请求体为 JSON，包含与前面一致的设备字段以及 code（来自 /oauth/code）。本步在 GetUcTokenStatus 中未携带 X-Pan-* 头，User-Agent 使用桌面 Chrome 样式。

GetUcTokenStatus 对响应的解析兼容：data.data.access_token、data.access_token、根级 access_token（见源码）。

响应示例（换 token 成功）

HTTP 200，响应体为双层状态：外层 code / message（如 200 / OK）表示接口网关或聚合层结果；令牌在 data 内，以 data.status == 0 且 data.errno == 0 作为 OAuth 子层成功判断。

json

{
  "code": 200,
  "message": "OK",
  "data": {
    "status": 0,
    "errno": 0,
    "error_info": "",
    "req_id": "8e59415ac2a899dc",
    "access_token": "eyJhbGciOiJIUzI1NiIsIlR5cGUiOiJKd3QiLCJ0eXAiOiJKV1QifQ.eyJvcGVuSWQiOiI5MWE2ZDUyNmM2MGE0NTVjYmZiNTc4ZTY5MzIxYjQ1ZSIsImV4cCI6MTc3NTc5ODg3OSwidG9rZW4iOiIxYjhlNjBiMzQwMGY0ZDQyOTViZmI2YTNkZWNlZTk3NiJ9.NxUGJs-kZfXqrRr8a1ZrkQGRWxEg5bTgR-FfQZ4EhuM",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsIlR5cGUiOiJKd3QiLCJ0eXAiOiJKV1QifQ.eyJvcGVuSWQiOiI5MWE2ZDUyNmM2MGE0NTVjYmZiNTc4ZTY5MzIxYjQ1ZSIsImV4cCI6MTgwNjczMDA3OSwidG9rZW4iOiI3ZWZmZTA5ZmI4MDY0YzhmOGI5MmVlMjdiYTBhZDZjMSJ9.x44z9JegRAlNHukrbZSi_lAho4qUDRI90NyxEZk2SM0",
    "expires_in": 604800,
    "scope": "netdisk"
  }
}

关键响应字段

字段路径	说明
`code` / `message`	外层业务包装；成功示例 `200` / `OK`
`data.access_token`	开放 API 访问令牌；写入 `DriveConfig.Token` 后供 `GET open-api-drive.uc.cn/file` 等
`data.refresh_token`	刷新用 JWT（载荷中含更长 `exp`）；可与 `uc.go` 内 `refreshToken` 衔接续期
`data.expires_in`	`access_token` 有效期（秒），示例 `604800`（7 天）
`data.scope`	授权范围，示例 `netdisk`
`data.req_id`	内层请求关联 ID
`data.status` / `data.errno` / `data.error_info`	OAuth 子层状态；成功时为 `0` / `0` / `""`

使用 `refresh_token` 刷新 `access_token`：`POST http://api.extscreen.com/ucdrive/token`

当你已经拥有 refresh_token（来自上一步 POST /token 的响应），播放前/播放中需要时，会调用本接口把 refresh_token 换成新的 access_token（并可能返回新的 refresh_token 用于轮换续期）。

项目内实现：backend/internal/drives/uc.go 的 ucExchangeRefreshForAccess() + resolveUCAccessTokenForPlayback()；播放流如果返回 status=-1 或 errno=10001，会触发一次刷新重试（ucFileStreamingResultNeedsRefresh()）。

接口概览

项目	值
方法	`POST`
URL	`http://api.extscreen.com/ucdrive/token`
Content-Type	`application/json`

请求体参数

参数	类型	必填	说明
`refresh_token`	string	是	上次登录/刷新得到的刷新凭证
`req_id`	string	是	请求关联 ID（项目内由 `device_id + timestamp` 计算）
`app_ver`	string	是	示例 `1.6.8`
`channel`	string	是	示例 `UCTVOFFICIALWEB`
`device_brand` / `device_id` / `device_model` / `device_name` / `build_device` / `build_product` / `device_gpu`	string	是	与服务端风控预期一致的设备参数
`platform`	string	是	示例 `tv`
`activity_rect`	object/string	是	示例 `{}`

请求示例（curl）

bash

curl --request POST \
  --url http://api.extscreen.com/ucdrive/token \
  --header 'Accept: */*' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Connection: keep-alive' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: PostmanRuntime-ApipostRuntime/1.1.0' \
  --data '{
    "activity_rect": "{}",
    "app_ver": "1.6.8",
    "build_device": "aosp",
    "build_product": "PCRT00",
    "channel": "UCTVOFFICIALWEB",
    "device_brand": "OPPO",
    "device_gpu": "Adreno (TM) 640",
    "device_id": "07b48aaba8a739356ab8107b5e230ad4",
    "device_model": "PCRT00",
    "device_name": "PCRT00",
    "platform": "tv",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsIlR5cCI6IkpXVCJ9.eyJvcGVuSWQiOiI5MWE2ZDUyNmM2MGE0NTVjYmZiNTc4ZTY5MzIxYjQ1ZSIsImV4cCI6MTgwNjczMzE1MiwidG9rZW4iOiI2M2Y5MGVhY2E2NDE0MTJmYmZhNjJmOTQyZjA4MjI2ZCJ9.NHeKUMjF-VOckaVHfnkctFnBbY_3H44J1uWNOLKwtGU",
    "req_id": "3bc67d929dd3eb79"
}'

响应示例（成功）

json

{
  "code": 200,
  "message": "OK",
  "data": {
    "status": 0,
    "errno": 0,
    "error_info": "",
    "req_id": "3bc67d929dd3eb79",
    "access_token": "eyJhbGciOiJIUzI1NiIsIlR5cCI6IkpXVCJ9.eyJvcGVuSWQiOiI5MWE2ZDUyNmM2MGE0NTVjYmZiNTc4ZTY5MzIxYjQ1ZSIsImV4cCI6MTc3NTgwMjI5MCwidG9rZW4iOiJjZDdkYWZiYjMwNjg0NTBkYTc5NDUyZDAyNWMzMDcyYiJ9.I3ZAA3OVeyZ4AjGokKdUrbG6WUZjR57BvRUvjdmxS_w",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsIlR5cCI6IkpXVCJ9.eyJvcGVuSWQiOiI5MWE2ZDUyNmM2MGE0NTVjYmZiNTc4ZTY5MzIxYjQ1ZSIsImV4cCI6MTgwNjczMzE1MiwidG9rZW4iOiI2M2Y5MGVhY2E2NDE0MTJmYmZhNjJmOTQyZjA4MjI2ZCJ9.NHeKUMjF-VOckaVHfnkctFnBbY_3H44J1uWNOLKwtGU",
    "expires_in": 604800,
    "scope": "netdisk"
  }
}

关键返回字段

字段	说明
`data.access_token`	短期访问令牌（用于 `GET open-api-drive.uc.cn/file`）
`data.refresh_token`	轮换续期用的刷新令牌（可用于下次刷新）
`data.expires_in`	`access_token` 有效期（秒）

3. 分享 Token + 首屏详情（v2 合并）

接口概览

项目	值
方法	`POST`
URL	`https://pc-api.uc.cn/1/clouddrive/share/sharepage/v2/detail?pr=UCBrowser&fr=pc`
作用	提交 `pwd_id`（及可选 `passcode`）一次返回 `token_info.stoken` 与首屏 `detail_info.list`，减少往返

请求体参数

参数	类型	必填	说明
`pwd_id`	string	是	分享链接 ID
`passcode`	string	否	提取码；无则可不传或空字符串
`force` / `page` / `size` / `fetch_banner` / `fetch_share`	多种	否	见 `uc.go` 内默认与业务开关

请求示例

bash

curl --request POST \
  --url 'https://pc-api.uc.cn/1/clouddrive/share/sharepage/v2/detail?pr=UCBrowser&fr=pc' \
  --header 'Content-Type: application/json' \
  --header 'Referer: https://drive.uc.cn' \
  --header 'Cookie: <你的 UC 网盘 Cookie>' \
  --data '{"pwd_id":"<pwd_id>"}'

响应示例（结构节选）

json

{
  "status": 200,
  "code": 0,
  "message": "ok",
  "data": {
    "token_info": {
      "stoken": "<base64>",
      "title": "分享标题",
      "expired_at": 4102416000000,
      "author": { "nick_name": "昵称", "member_type": "SUPER_VIP" }
    },
    "detail_info": {
      "is_owner": 0,
      "list": [
        {
          "fid": "8028a82ace9f4e88865c3597b395d949",
          "file_name": "目录名",
          "dir": true,
          "file": false,
          "share_fid_token": "e96a55deb16a179bb43bd7a0fcba4add",
          "include_items": 2
        }
      ]
    }
  },
  "metadata": {
    "detail_meta": { "_page": 1, "_total": 1, "video_total": 0 }
  }
}

关键响应字段

字段	说明	后续用途
`data.token_info.stoken`	分享会话令牌	`sharepage/detail`、`sharepage/save` 的 `stoken`
`data.token_info.title` / `expired_at`	分享标题与过期时间	展示与过期判断
`data.detail_info.list[].fid`	目录/文件 ID	子目录列表、转存、播放链路
`data.detail_info.list[].share_fid_token`	分享文件 token	与 `fid` 成对用于转存
`data.detail_info.list[].dir` / `file`	类型标记	UI 与后续接口分支

使用说明

首屏 list 可能不完整，深层目录需继续调「分享目录分页列表」。
stoken 需 URL 编码后作为 GET 参数传递。
成功判断建议以 status=200 && code=0 为准；message 可能为空字符串。

4. 分享目录分页列表

接口概览

项目	值
方法	`GET`
URL	`https://pc-api.uc.cn/1/clouddrive/share/sharepage/detail`
作用	按 `pdir_fid` 分页拉取分享内文件/文件夹，需有效 `pwd_id` + `stoken`

Query 参数

参数	类型	必填	说明
`pwd_id`	string	是	分享 ID
`stoken`	string	是	v2/detail 或独立 token 接口返回，需 URL 编码
`pdir_fid`	string	是	父目录 `fid`，根目录一般 `0`
`_page`	number	是	页码，从 1 开始
`_size`	number	是	每页条数，常用 `100`
`_sort`	string	否	如 `file_type:asc,file_name:asc`
`pr`	string	否	常见 `UCBrowser`
`fr`	string	否	常见 `pc`

请求示例

bash

curl --request GET \
  --url 'https://pc-api.uc.cn/1/clouddrive/share/sharepage/detail?_page=1&_size=100&fr=pc&pdir_fid=0&pr=UCBrowser&pwd_id=<id>&stoken=<urlencoded_stoken>' \
  --header 'Cookie: <你的 UC 网盘 Cookie>' \
  --header 'Referer: https://drive.uc.cn'

响应说明

外层为 status / code / data.list / metadata，字段语义与夸克 sharepage/detail 相近。
文件项常见：format_type、video_max_resolution、preview_url、thumbnail、duration、share_fid_token 等。

使用说明

进入子目录时将 pdir_fid 改为目标目录的 fid。
转存前务必保留每条目的 fid 与 share_fid_token 一一对应关系。

5. 网盘内文件排序列表（`file/sort`）

接口概览

项目	值
方法	`GET`
URL	`https://pc-api.uc.cn/1/clouddrive/file/sort`
作用	登录用户个人网盘目录列表，支持分页与多字段排序（找转存目录、列举已转存文件等）

Query 参数

参数	类型	必填	说明
`_page`	number	是	页码，从 1 开始
`_size`	number	是	每页条数，如 `200`
`_sort`	string	否	如 `file_type:asc,updated_at:desc`（目录优先 + 最近更新在前）
`pdir_fid`	string	是	父目录 FID；根目录视账号策略（常见为具体根 `fid` 或 `0`，以抓包为准）
`pr`	string	否	常见 `UCBrowser`
`fr`	string	否	常见 `pc`

请求示例

bash

curl --request GET \
  --url 'https://pc-api.uc.cn/1/clouddrive/file/sort?_page=1&_size=200&_sort=file_type:asc,updated_at:desc&fr=pc&pdir_fid=<父目录fid>&pr=UCBrowser' \
  --header 'Accept: */*' \
  --header 'Cookie: <你的 UC 网盘 Cookie>'

响应示例（节选）

json

{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775186738,
  "data": {
    "last_view_list": [],
    "recent_file_list": [],
    "list": [
      {
        "fid": "b05375027dc04b3a9e2660c830c9a1da",
        "file_name": "example.mkv",
        "pdir_fid": "fe69f2ccab0b42aebd5d405df50ae35d",
        "category": 1,
        "file_type": 1,
        "size": 4626056097,
        "format_type": "video/x-matroska",
        "thumbnail": "https://pc-api.uc.cn/1/clouddrive/file/video/thumbnail?fid=b05375027dc04b3a9e2660c830c9a1da",
        "preview_url": "https://pc-api.uc.cn/1/clouddrive/file/video/preview?fid=b05375027dc04b3a9e2660c830c9a1da",
        "video_max_resolution": "super",
        "duration": 6560,
        "dir": false,
        "file": true,
        "created_at": 1775186616995,
        "updated_at": 1775186616995
      }
    ]
  },
  "metadata": {
    "_size": 200,
    "req_id": "99fotg-29582660794b41",
    "_page": 1,
    "_count": 1,
    "_total": 0
  }
}

关键响应字段

字段	说明	后续用途
`data.list`	当前目录下条目	文件管理页、转存目标校验
`data.list[].fid`	文件/目录主键	`file/v2/play`、`file/delete`、`pdir_fid` 下钻
`data.list[].dir` / `file`	类型	区分目录与文件操作
`data.list[].pdir_fid`	父目录	面包屑与路径校验
`data.list[].thumbnail` / `preview_url`	缩略图与预览接口 URL	列表封面（非直链整片）
`data.list[].video_max_resolution` / `duration`	视频能力摘要	展示与播放策略
`metadata._page` / `_size` / `_count`	分页信息	翻页；`_total` 有时为 `0`，需结合 `_count` 与 `list` 长度

使用说明

与夸克类似：metadata._total 可能未返回真实总数，分页勿单依赖 _total。
视频文件可直接用 fid 调用「获取播放信息」。
排序字符串与客户端保持一致可减少服务端默认排序差异。

6. 删除文件

接口概览

项目	值
方法	`POST`
URL	`https://pc-api.uc.cn/1/clouddrive/file/delete?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6`
作用	按 FID 批量删除网盘内文件或目录（项目内清理转存临时文件等）

Query 参数

参数	类型	必填	说明
`pr`	string	否	常见 `UCBrowser`
`fr`	string	否	常见 `pc`
`sys`	string	否	系统标识，如 `darwin`、`win32`
`ve`	string	否	客户端版本号，需与抓包一致

请求体参数

参数	类型	必填	说明
`action_type`	number	是	删除场景固定为 `2`（与夸克一致）
`filelist`	string[]	是	待删除的 `fid` 列表
`exclude_fids`	string[]	否	排除不删的 `fid`，无则 `[]`

请求示例

bash

curl --request POST \
  --url 'https://pc-api.uc.cn/1/clouddrive/file/delete?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的 UC 网盘 Cookie>' \
  --data '{"action_type":2,"exclude_fids":[],"filelist":["fc43bdc73de444509cb94c05d32ca14f"]}'

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

json

{
  "status": 400,
  "code": 23004,
  "message": "[文件已经删除,请稍后重试]",
  "req_id": "9f07rl-295826d0aecbd2",
  "timestamp": 1775186795
}

关键响应字段

字段	说明	后续用途
`status` / `code`	外层 HTTP 语义与业务码	成功多为 `200` + `0`；重复删除常见 `23004`
`message`	文案提示	日志与用户提示
`req_id`	请求追踪 ID	排障

使用说明

成功时一般为 status=200 且 code=0（具体 data 以抓包为准）。
code=23004 等业务错误可视为幂等：目标已删除即达成清理目的。
批量删除注意单次 filelist 长度限制；失败可结合 req_id 单条重试。

7. 转存分享文件（`sharepage/save`）

接口概览

项目	值
方法	`POST`
URL	`https://pc-api.uc.cn/1/clouddrive/share/sharepage/save?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6`
作用	将分享中的文件转存到个人网盘指定目录，返回任务信息；同步场景下内嵌 `task_resp`

请求体参数

参数	类型	必填	说明
`fid_list`	string[]	是	分享侧文件 FID 列表
`fid_token_list`	string[]	是	与 `fid_list` 按索引一一对应的分享 token（如 `share_fid_token`）
`pwd_id`	string	是	分享链接 ID
`stoken`	string	是	分享访问令牌
`to_pdir_fid`	string	是	保存到的个人网盘目录 FID
`pdir_fid`	string	否	分享内源目录 FID，根下常传 `""`
`scene`	string	否	场景标记，示例 `link`

请求示例

bash

curl --request POST \
  --url 'https://pc-api.uc.cn/1/clouddrive/share/sharepage/save?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的 UC 网盘 Cookie>' \
  --data '{
    "fid_list": ["396638c9e45343eeb434d2889cb468bb"],
    "fid_token_list": ["04e9c7c2471e4e8330984c85a59af19e"],
    "pdir_fid": "",
    "pwd_id": "b26cf08308144",
    "scene": "link",
    "stoken": "P003Gyoh6WTrNVnfyxbfzKOQGBzgxVOGLwYV6h1UAXo=",
    "to_pdir_fid": "fe69f2ccab0b42aebd5d405df50ae35d"
  }'

响应示例

json

{
  "status": 200,
  "code": 0,
  "message": "ok",
  "timestamp": 1775186953,
  "data": {
    "task_id": "be87e86d7cd4416cbef59f0368eed437",
    "task_sync": true,
    "task_resp": {
      "status": 200,
      "code": 0,
      "message": "ok",
      "timestamp": 1775186953,
      "data": {
        "task_id": "be87e86d7cd4416cbef59f0368eed437",
        "event_id": "9f3uiq-295827fb09deaf",
        "task_type": 17,
        "task_title": "分享-转存",
        "status": 2,
        "created_at": 1775186948649,
        "finished_at": 1775186948721,
        "save_as": {
          "save_as_select_top_fids": ["d87cac8f2d1a4448a12e015df34e791e"],
          "save_as_top_fids": ["d87cac8f2d1a4448a12e015df34e791e"],
          "save_as_sum_num": 1,
          "to_pdir_fid": "fe69f2ccab0b42aebd5d405df50ae35d",
          "to_pdir_name": "omnibox",
          "remain_capacity": 1085496142103,
          "min_save_file_size": 4626056097
        }
      },
      "metadata": {}
    }
  },
  "metadata": {
    "tq_gap": 500
  }
}

关键响应字段

字段	说明	后续用途
`data.task_id`	任务 ID	与「查询转存任务」联动
`data.task_sync`	是否同步返回 `task_resp`	`false` 时必须轮询 task
`data.task_resp.data.status`	任务状态	示例 `2` 表示已完成（与夸克 task 语义一致，具体以服务端为准）
`data.task_resp.data.save_as.save_as_top_fids`	转存后的个人网盘 FID	播放/下载主键，建议持久化
`data.task_resp.data.save_as.to_pdir_fid`	实际落盘目录	校验与列表展示
`data.task_resp.data.save_as.remain_capacity`	剩余空间（字节）	容量提示
`metadata.tq_gap`	建议轮询间隔（毫秒）	异步任务节流

使用说明

fid_list 与 fid_token_list 必须按索引严格对应。
task_sync=false 或未含完整结果时，使用下一节任务查询接口按 tq_gap 轮询。
转存完成后播放链路使用 个人网盘 fid（save_as_top_fids），而非分享侧 fid。

8. 查询转存任务状态

接口概览

项目	值
方法	`GET`
URL	`https://pc-api.uc.cn/1/clouddrive/task`
作用	根据 `task_id` 查询转存任务进度与产物 FID（与 `uc.go` 中轮询逻辑一致）

Query 参数

参数	类型	必填	说明
`task_id`	string	是	`save` 返回的 `task_id`
`retry_index`	number	否	轮询序号，从 `0` 递增
`pr`	string	否	`UCBrowser`
`fr`	string	否	`pc`
`sys` / `ve`	string	否	与删除、播放等接口保持一致

请求示例

bash

curl --request GET \
  --url 'https://pc-api.uc.cn/1/clouddrive/task?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6&task_id=<task_id>&retry_index=0' \
  --header 'Cookie: <你的 UC 网盘 Cookie>'

使用说明

终态后读取 data.save_as.save_as_top_fids 作为个人网盘文件 fid。
轮询频率参考返回中的 metadata.tq_gap，避免限流。

9. 获取播放信息（`file/v2/play`）

接口概览

项目	值
方法	`POST`
URL	`https://pc-api.uc.cn/1/clouddrive/file/v2/play?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6`
作用	根据个人网盘文件 `fid` 获取多清晰度转码信息、可播直链、拖拽预览雪碧图等（需登录 Cookie）

请求体参数

参数	类型	必填	说明
`fid`	string	是	个人网盘中的文件 FID（一般为转存后的 `fid`）
`resolutions`	string	否	期望清晰度，逗号分隔，如 `normal,low,high,super,2k,4k`
`supports`	string	否	能力集合，如 `fmp4`

请求示例

bash

curl --request POST \
  --url 'https://pc-api.uc.cn/1/clouddrive/file/v2/play?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的 UC 网盘 Cookie>' \
  --data '{"fid":"b05375027dc04b3a9e2660c830c9a1da","resolutions":"normal,low,high,super,2k,4k","supports":"fmp4"}'

响应示例（精简）

完整抓包中含大量 seek_preview_data.preview_sprite_infos（雪碧图 CDN URL 与时间戳数组），此处仅保留结构要点：

json

{
  "status": 200,
  "code": 0,
  "message": "ok",
  "data": {
    "default_resolution": "low",
    "origin_default_resolution": "low",
    "video_list": [
      {
        "resolution": "super",
        "right": "svip",
        "member_right": "svip",
        "trans_status": "success",
        "accessable": false,
        "supports_format": "mp4"
      },
      {
        "resolution": "low",
        "right": "normal",
        "member_right": "normal",
        "trans_status": "success",
        "accessable": true,
        "supports_format": "mp4",
        "video_info": {
          "duration": 6559,
          "format": "mp4",
          "width": 480,
          "height": 270,
          "url": "https://video-play-c-zb.drive.uc.cn/...",
          "streams": {
            "video_stream_list": [],
            "audio_stream_list": [],
            "subtitle_stream_list": [{ "index": "2", "lang": "eng" }]
          }
        }
      }
    ],
    "audio_list": [
      {
        "type": "dolby_eac3",
        "right": "z_vip",
        "accessable": false
      }
    ],
    "file_name": "example.mkv",
    "size": 4626056097,
    "thumbnail": "https://pc-api.uc.cn/1/clouddrive/file/video/thumbnail?fid=...",
    "seek_preview_data": {
      "total_frame_count": 1093,
      "preview_sprite_infos": [
        { "url": "https://img-view-c-zb.drive.uc.cn/...", "frame_count": 30, "times": [6004, 12004] }
      ]
    },
    "meta": {
      "duration": 6560,
      "width": 1920,
      "height": 1080,
      "codec": "h264"
    },
    "obj_key": "G338zI9Vi115cmx2114csUWARvRJFjpA5IaMbv5gk|",
    "has_seek_preview_data": true
  }
}

关键响应字段

字段	说明	后续用途
`data.default_resolution`	默认清晰度 key	播放器首选项
`data.video_list`	各清晰度条目	清晰度切换
`data.video_list[].accessable`	当前账号是否可播该档	注意字段名为 `accessable`
`data.video_list[].video_info.url`	转码后直链（MP4 等）	实际播放地址；带时效签名
`data.video_list[].right` / `member_right`	权益等级	`svip` 等与会员提示
`data.video_list[].trans_status`	转码状态	仅 `success` 且可访问项适合作为播放源
`data.audio_list`	增强音轨能力	杜比等提示
`data.seek_preview_data`	拖拽预览雪碧图	`times` 多为毫秒时间戳，映射进度条
`data.meta`	源文件元数据	信息面板
`data.obj_key`	对象键	部分下载/鉴权链路关联（以服务端为准）

使用说明

优先选用 accessable=true 且 trans_status=success 的 video_info.url。
高清档可能 accessable=false，需降级到 normal 可访问清晰度。
video_info.url 过期后需重新请求本接口换链。
与夸克相同：接口使用 accessable 拼写，解析时勿写成 accessible。

10. Open API 播放：`GET /file`

使用 文档内「UC Open API：access_token / refresh_token 获取」 得到并持久化的 refresh_token（播放前会先续期换成短期 access_token），调用本接口拉取多清晰度 video_info（含 CDN URL），不依赖 pc-api.uc.cn 的浏览器 Cookie。实现：uc.go 的 getDownloadByToken。

接口概览

项目	值
方法	`GET`
URL	`https://open-api-drive.uc.cn/file`
作用	使用 `access_token` 与 `fid` 等换取播放地址

Query 要点

access_token、fid、method=streaming、platform=tv、resolution、support（如 dolby_vision）、以及 device_id、app_ver、channel 等设备参数（见 uc.go 与日志）。

响应要点

常见 status: 0，data.video_info[] 含 resolution、url、trans_status（raw / success）等。

11. 获取下载地址（`file/download`）

接口概览

项目	值
方法	`POST`
URL	`https://pc-api.uc.cn/1/clouddrive/file/download?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6`
作用	根据个人网盘文件 `fid` 获取原文件直链 `download_url`、分片建议 `range_size`、校验 `md5` 等；`uc.go` 中 `GetVideoPlayInfo` 在 Cookie 模式下用其补充「原码」播放地址，`GetDownloadURL` / `GetDownloadURLAndFileName` 直接取链

Query 参数

参数	类型	必填	说明
`pr`	string	否	`UCBrowser`
`fr`	string	否	`pc`
`sys`	string	否	如 `darwin`、`win32`
`ve`	string	否	客户端版本，需与抓包一致

请求体参数

参数	类型	必填	说明
`fids`	string[]	是	个人网盘文件 FID 列表；项目内 `GetDownloadURL` 每次传单个 `fid`
`ab_tag` / `cn_sw` / `token` 等	多种	否	夸克侧常见扩展；UC 当前代码仅传 `fids`，其它以服务端与抓包为准

请求示例

bash

curl --request POST \
  --url 'https://pc-api.uc.cn/1/clouddrive/file/download?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6' \
  --header 'Content-Type: application/json' \
  --header 'Referer: https://drive.uc.cn' \
  --header 'Cookie: <你的 UC 网盘 Cookie>' \
  --data '{"fids":["421663c6c2484a9e829be723ee989ff9"]}'

响应示例（节选）

data 为数组，与 fids 顺序对应；单文件场景取下标 0。下列省略部分展示字段（如 cover_face_boundary），download_url 为带签名参数的长 URL，实际使用取完整返回值。

json

{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775189259,
  "data": [
    {
      "fid": "421663c6c2484a9e829be723ee989ff9",
      "file_name": "War.Machine.2026.1080p.NF.WEB-DL.H264.DDP5.1.Atmos.mkv",
      "pdir_fid": "f1e8397fbad6456da007426d045b9796",
      "category": 1,
      "file_type": 1,
      "obj_key": "a002e743331f43eaac12b65e8dc062e3",
      "size": 4626056097,
      "format_type": "video/x-matroska",
      "download_url": "https://dl-pc-zb-w.drive.uc.cn/...&filename=War.Machine.2026....mkv",
      "preview_url": "https://pc-api.uc.cn/1/clouddrive/file/video/preview?fid=421663c6c2484a9e829be723ee989ff9",
      "thumbnail": "https://pc-api.uc.cn/1/clouddrive/file/video/thumbnail?fid=421663c6c2484a9e829be723ee989ff9",
      "video_max_resolution": "super",
      "md5": "ecf535ece872c6ccae7fe713a2f9fdfa",
      "range_size": 20485760,
      "duration": 6560,
      "video_width": 1920,
      "video_height": 1080,
      "dir": false,
      "file": true
    }
  ],
  "metadata": {
    "acc2": "Ng==",
    "acc1": "MQ=="
  }
}

关键响应字段

字段	说明	后续用途
`data[].download_url`	原文件下载/直链（含 `auth_key`、`token` 等签名参数）	原码播放、下载代理、`ProxyStream` 拉流
`data[].fid` / `file_name` / `size`	文件标识与元信息	任务展示与校验
`data[].range_size`	建议分片大小（字节）	断点续传、多线程下载分块
`data[].md5`	文件摘要	完整性校验
`data[].format_type`	MIME 类型	判断容器/解码策略
`data[].preview_url` / `thumbnail`	官方预览与封面 URL	非整片直链，与 `download_url` 区分
`metadata`	扩展控制字段	本例为 `acc1`/`acc2`；其它环境下可能出现与夸克类似的 `refresh_token`（以实际响应为准）

使用说明

GetDownloadURL（uc.go）解析路径：data[0].download_url；失败则播放链路仅保留 file/v2/play 转码地址。
download_url 带时效，失效需重新请求本接口。
请求需携带有效网盘 Cookie；FID 必须是已转存到个人网盘后的 fid，不能直接使用分享侧 fid（需先 sharepage/save）。

12. 创建目录

接口概览

项目	值
方法	`POST`
URL	`https://pc-api.uc.cn/1/clouddrive/file?pr=UCBrowser&fr=pc`
作用	在指定父目录下创建新文件夹；`uc.go` 转存前用于确保目标目录存在

Query 参数

参数	类型	必填	说明
`pr`	string	否	常见 `UCBrowser`
`fr`	string	否	常见 `pc`

请求体参数

参数	类型	必填	说明
`pdir_fid`	string	是	父目录 FID；在根下创建时传 `"0"`
`file_name`	string	是	新目录名称
`dir_path`	string	否	目录路径；根下创建常传空字符串 `""`
`dir_init_lock`	boolean	否	目录初始化锁，示例为 `false`

请求示例

bash

curl --request POST \
  --url 'https://pc-api.uc.cn/1/clouddrive/file?pr=UCBrowser&fr=pc' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: <你的 UC 网盘 Cookie>' \
  --data '{
    "dir_init_lock": false,
    "dir_path": "",
    "file_name": "omnibox",
    "pdir_fid": "0"
  }'

响应示例

json

{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775187851,
  "data": {
    "finish": true,
    "fid": "b21e89139ac04a338d92967120be03c7"
  },
  "metadata": {}
}

关键响应字段

字段	说明	后续用途
`data.finish`	是否创建完成	异步场景可据此决定是否轮询（本例为同步完成）
`data.fid`	新建目录 FID	作为 `sharepage/save` 的 `to_pdir_fid`、`file/sort` 的 `pdir_fid`

使用说明

与 backend/internal/drives/uc.go 中创建保存目录逻辑一致：根目录 pdir_fid="0"、dir_path=""、dir_init_lock=false。
同名目录是否允许重复以服务端策略为准；可先 file/sort 查重再创建。
成功判断建议以 status=200 && code=0 为准。

13. 获取会员状态（`member`）

接口概览

项目	值
方法	`GET`
URL	`https://pc-api.uc.cn/1/clouddrive/member`
作用	查询会员类型、容量、转存/离线下载余量等；`backend/internal/drives/auth/uc.go` 用于 Cookie 校验

Query 参数

参数	类型	必填	说明
`pr`	string	否	`UCBrowser`
`fr`	string	否	`pc`
`fetch_subscribe`	string/boolean	否	是否拉取订阅相关信息，示例 `true`
`_ch`	string	否	场景渠道，示例 `home`

请求示例

bash

curl --request GET \
  --url 'https://pc-api.uc.cn/1/clouddrive/member?pr=UCBrowser&fr=pc&fetch_subscribe=true&_ch=home' \
  --header 'Accept: application/json, text/plain, */*' \
  --header 'Cookie: <你的 UC 网盘 Cookie>'

响应示例

json

{
  "status": 200,
  "code": 0,
  "message": "",
  "timestamp": 1775188383,
  "data": {
    "member_type": "VIP",
    "image_backup": 1,
    "deep_recycle_stat": {
      "recycle_normal_serve_days": 10,
      "recycle_svip_serve_days": 30,
      "recycle_zvip_serve_days": 60,
      "recycle_vip_serve_days": 10,
      "recycle_pay_serve_days": 30,
      "deep_recycle_serve_days": 180
    },
    "created_at": 1716383798000,
    "member_info": {
      "video_save_to_uses": 0,
      "video_save_to_remains": 2,
      "file_save_to_remains": 200,
      "offline_download_remains": 5,
      "member_type_map": {
        "MINI_VIP": {
          "video_save_to_total": 10
        }
      }
    },
    "acc_status": 0,
    "secret_use_capacity": 4763373479,
    "use_capacity": 4763373479,
    "video_backup": 1,
    "extend_capacity_composition": {},
    "is_new_user": false,
    "member_status": {
      "MINI_VIP": "UNPAID",
      "Z_VIP": "UNPAID",
      "SUPER_VIP": "UNPAID",
      "VIP": "UNPAID"
    },
    "is_real_name": true,
    "secret_total_capacity": 1099511627776,
    "subscribe_pay_channel_map": {},
    "exp_at": 1775491200000,
    "subscribe_status_map": {},
    "total_capacity": 1099511627776,
    "vip_exp_at": 1775491200000
  },
  "metadata": {
    "range_size": 10485760,
    "server_cur_time": 1775188383320
  }
}

关键响应字段

字段	说明	后续用途
`data.member_type`	当前会员类型（如 `VIP`）	权益与清晰度策略参考
`data.exp_at` / `data.vip_exp_at`	会员到期时间（毫秒）	到期提示与降级
`data.total_capacity` / `use_capacity`	总容量 / 已用（字节）	转存前空间校验
`data.secret_total_capacity` / `secret_use_capacity`	私密空间容量口径	与列表展示一致时使用
`data.member_info.video_save_to_remains`	视频转存剩余次数	转存前预校验
`data.member_info.file_save_to_remains`	文件转存剩余额度	批量转存控制
`data.member_info.offline_download_remains`	离线下载剩余次数	下载任务前判断
`data.member_status`	各等级支付状态	权益页展示
`data.deep_recycle_stat`	回收站/深度回收保留天数	产品说明与提示文案
`metadata.server_cur_time`	服务端当前时间（毫秒）	与 `exp_at` 对齐判断
`metadata.range_size`	建议分片大小（字节）	与下载分片策略一致时可复用

使用说明

播放/转存链路中若遇 svip 等权限提示，可结合 member_type 与 member_info 做前置判断。
message 可能为空，成功以 status=200 && code=0 为准。

14. 扫码登录相关（CAS，`api.open.uc.cn`）

实现参考：backend/internal/handlers/qr_auth/quark_uc.go（GetQrCode / GetCookie，type=uc）。以下为浏览器/客户端真实调用形态，便于对照抓包与排障。

12.1 获取扫码登录 Token

接口概览

项目	值
方法	`GET`
URL	`https://api.open.uc.cn/cas/ajax/getTokenForQrcodeLogin`
作用	换取二维码登录会话 `token`（写入扫码链接，用户手机 UC 扫码）

Query 参数

参数	类型	必填	说明
`client_id`	string	是	UC 网盘扫码固定为 `381`（与代码一致）
`v`	string	是	协议版本，示例 `1.2`
`request_id`	number	是	毫秒时间戳，防缓存

请求示例

bash

curl --request GET \
  --url 'https://api.open.uc.cn/cas/ajax/getTokenForQrcodeLogin?client_id=381&v=1.2&request_id=1775188320300' \
  --header 'Referer: https://drive.uc.cn' \
  --header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) UCBrowser/15.0.0 Chrome/100.0.4896.160 Safari/537.36'

响应说明（结构）

外层 JSON 中含 data.members.token 字符串，作为后续「用扫码 token 换 service_ticket」的 token 参数。
项目内将该值作为 query_token 返回给前端；二维码内容为 https://su.uc.cn/1_n0ZCv?...&token=<token>&client_id=381&...（见 quark_uc.go）。

12.2 扫码完成后换取 Service Ticket

接口概览

项目	值
方法	`GET`
URL	`https://api.open.uc.cn/cas/ajax/getServiceTicketByQrcodeToken`
作用	用手机确认登录后，用步骤 12.1 的 `token` 轮询换取 `service_ticket`，再换 Web Cookie

Query 参数

参数	类型	必填	说明
`token`	string	是	12.1 返回的 `data.members.token`（即扫码会话 token）
`client_id`	string	是	`381`
`v`	string	是	`1.2`
`request_id`	number	是	毫秒时间戳
`__t`	number	否	与 `request_id` 相同或同为时间戳；代码中与 `request_id` 一并传入

请求示例

bash

curl --request GET \
  --url 'https://api.open.uc.cn/cas/ajax/getServiceTicketByQrcodeToken?token=<query_token>&__t=1775188320300&client_id=381&v=1.2&request_id=1775188320300' \
  --header 'Referer: https://drive.uc.cn' \
  --header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) UCBrowser/15.0.0 Chrome/100.0.4896.160 Safari/537.36'

响应说明（逻辑，与 `quark_uc.go` 解析一致）

完整 JSON 样例可后续补档。业务侧按 status 区分：

`status`（数值）	含义（项目内处理）
`2000000`	成功，从 `data.members.service_ticket` 取票据
`50004001`	未完成扫码，需稍后重试轮询
`50004002`	二维码无效或已过期
其他	读取 `message` 作为错误说明

成功后的下一步（代码路径）：

GET https://drive.uc.cn/account/info?st=<service_ticket>，收集 Set-Cookie。
GET https://pc-api.uc.cn/1/clouddrive/config?pr=UCBrowser&fr=pc&sys=darwin&ve=1.8.6，带上上一步 Cookie，再合并 Set-Cookie。
合并后的 Cookie 字符串即为网盘 API 可用的登录态（与手动导出 Cookie 等价思路）。

使用说明

getServiceTicketByQrcodeToken 在未扫码完成时会长期返回「未完成」类状态，需前端按间隔轮询（与夸克扫码流程相同）。
Referer / User-Agent 建议与真实 UC 网盘 Web 一致，降低风控差异。

15. CDN 直链拉流

播放域名示例：https://video-play-c-zb.drive.uc.cn/...（随清晰度与区域变化）。
一般为 GET/HEAD，Content-Type: video/mp4，支持 Range → 206 Partial Content。

16. 与夸克文档的差异小结

维度	UC	夸克（参考 `quark.md`）
API 主机	`pc-api.uc.cn`	`drive-pc.quark.cn`、`drive-h.quark.cn` 等
产品参数	`pr=UCBrowser`	`pr=ucpro`
分享首屏	v2 合并接口 `sharepage/v2/detail`	独立 `sharepage/token` + `detail`
扫码 CAS	`api.open.uc.cn`，`client_id=381`	`uop.quark.cn`，`client_id=532`
Open API Token	`open-api-drive.uc.cn` OAuth + `api.extscreen.com/ucdrive/token`（见文首「UC Open API：access_token / refresh_token 获取」）	本文未覆盖夸克侧同类流程
会话/社交下载	本文未展开（若需可单独补档）	`quark.md` 含 `batch_send`、`acquire_dl_token`

17. 项目内调用关系（`uc.go` / `auth/uc.go` / `qr_auth` 摘要）

播放：缓存命中则跳过转存；否则 saveSharedFiles → file/v2/play；若配置 Token 则优先 open-api-drive 视频列表，否则从播放结果拼转码列表并调用 file/download 追加原码条目（见 GetVideoPlayInfo）。
转存：sharepage/save → 若 task_sync 为假则轮询 clouddrive/task → 得到 save_as_top_fids 供播放与下载。
目录：file/sort 查找或 file 创建目录 → 转存目标 to_pdir_fid。
清理：clearSaveDir 通过 file/sort 列目录后 file/delete；23004 可按幂等处理。
Cookie 校验：auth/uc.go 请求 clouddrive/member（见本文 §13）。
扫码登录（Cookie）：qr_auth/quark_uc.go 中 UC 分支见本文 §18.1 与 §14。
扫码登录（Open API access_token）：同文件 GetUcTokenQrCode / GetUcTokenStatus，对应文首「UC Open API：access_token / refresh_token 获取」与 §18.4。

18. 项目中 UC 接口调用示意图

下列示意图与当前 backend/internal/drives/uc.go、backend/internal/handlers/qr_auth/quark_uc.go 行为对齐，便于把「文档里的 URL」和「代码入口」对应起来。

18.1 扫码登录（`qr_auth/quark_uc.go`，`type=uc`）

18.2 网盘驱动主链路（`internal/drives/uc.go`）

说明：

Play 会先请求 file/v2/play；若 config.RefreshToken 或 config.Token 非空且 getDownloadByToken 返回非空列表，则仅用 Open API 结果组装 VideoPlayInfo（忽略本次 play 的转码列表与 file/download 原码拼接）；否则解析 play 的 video_list，并调用 GetDownloadURL（file/download）把原文件 URL 插到列表首位。
Down 与 Play 共用同一套「个人网盘 fid」前提：分享文件需先经 Save 得到 save_as_top_fids（或命中转存 fid 缓存）。
Stream 不单独调用 pc-api 业务 JSON 接口，而是对已拿到的播放/下载 URL 带 Cookie 或 Token 策略头做转发（见 buildUCHeaders）。

18.3 配置校验（`internal/drives/auth/uc.go`）

与 §13 会员接口 对应；与 §18.1 产出的 Cookie 为同一套登录态的不同获取方式（扫码 vs 手动粘贴）。

18.4 Open API Token 扫码（`GetUcTokenQrCode` / `GetUcTokenStatus`）

与文首「UC Open API：access_token / refresh_token 获取」对应；与 §18.1 Web Cookie 扫码 为两条独立链路（Token 走 X-Pan-* 签名 + TV 设备参数，不经过 drive.uc.cn/account/info）。

UC 网盘接口清单 ​

1. UC Web Cookie 扫码登录（CAS） ​

获取扫码会话 Token（生成二维码前置） ​

接口概览 ​

Query 参数 ​

请求示例 ​

说明（与项目实现一致） ​

扫码后轮询换取 service_ticket ​

接口概览 ​

请求示例 ​

响应示例（成功） ​

状态说明（项目轮询逻辑） ​

使用 service_ticket 获取用户信息与首批 Cookie ​

接口概览 ​

请求示例 ​

响应示例（业务体） ​

关键点 ​

续签/补齐 Cookie（最终可用登录态） ​

接口概览 ​

请求说明 ​

2. UC Open API：access_token / refresh_token 获取 ​

获取授权二维码 GET /oauth/authorize ​

接口概览 ​

必选请求头（签名） ​

Query 参数（与项目构造一致） ​

签名算法（X-Pan-Token） ​

请求示例（结构示意） ​

响应示例（成功） ​

查询扫码结果 GET /oauth/code ​

接口概览 ​

请求示例（结构示意） ​

响应示例（二维码过期） ​

status / errno 与项目映射（GetUcTokenStatus） ​

用 code 换取 access_token + refresh_token：POST /token ​

响应示例（换 token 成功） ​

关键响应字段 ​

使用 refresh_token 刷新 access_token：POST http://api.extscreen.com/ucdrive/token ​

接口概览 ​

请求体参数 ​

请求示例（curl） ​

响应示例（成功） ​

关键返回字段 ​

3. 分享 Token + 首屏详情（v2 合并） ​

接口概览 ​

请求体参数 ​

请求示例 ​

响应示例（结构节选） ​

关键响应字段 ​

使用说明 ​

4. 分享目录分页列表 ​

接口概览 ​

Query 参数 ​

请求示例 ​

响应说明 ​

使用说明 ​

5. 网盘内文件排序列表（file/sort） ​

接口概览 ​

Query 参数 ​

请求示例 ​

响应示例（节选） ​

关键响应字段 ​

使用说明 ​

6. 删除文件 ​

接口概览 ​

Query 参数 ​

请求体参数 ​

请求示例 ​

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

关键响应字段 ​

使用说明 ​

7. 转存分享文件（sharepage/save） ​

接口概览 ​

请求体参数 ​

请求示例 ​

响应示例 ​

关键响应字段 ​

使用说明 ​

8. 查询转存任务状态 ​

接口概览 ​

Query 参数 ​

UC 网盘接口清单

1. UC Web Cookie 扫码登录（CAS）

获取扫码会话 Token（生成二维码前置）

接口概览

Query 参数

请求示例

说明（与项目实现一致）

扫码后轮询换取 `service_ticket`

接口概览

请求示例

响应示例（成功）

状态说明（项目轮询逻辑）

使用 `service_ticket` 获取用户信息与首批 Cookie

接口概览

请求示例

响应示例（业务体）

关键点

续签/补齐 Cookie（最终可用登录态）

接口概览

请求说明

2. UC Open API：access_token / refresh_token 获取

获取授权二维码 `GET /oauth/authorize`

接口概览

必选请求头（签名）

Query 参数（与项目构造一致）

签名算法（`X-Pan-Token`）

请求示例（结构示意）

响应示例（成功）

查询扫码结果 `GET /oauth/code`

接口概览

请求示例（结构示意）

响应示例（二维码过期）

`status` / `errno` 与项目映射（`GetUcTokenStatus`）

用 `code` 换取 `access_token` + `refresh_token`：`POST /token`

响应示例（换 token 成功）

关键响应字段

使用 `refresh_token` 刷新 `access_token`：`POST http://api.extscreen.com/ucdrive/token`

接口概览

请求体参数

请求示例（curl）

响应示例（成功）

关键返回字段

3. 分享 Token + 首屏详情（v2 合并）

接口概览

请求体参数

请求示例

响应示例（结构节选）

关键响应字段

使用说明

4. 分享目录分页列表

接口概览

Query 参数

请求示例

响应说明

使用说明

5. 网盘内文件排序列表（`file/sort`）

接口概览

Query 参数

请求示例

响应示例（节选）

关键响应字段

使用说明

6. 删除文件

接口概览

Query 参数

请求体参数

请求示例

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

关键响应字段

使用说明

7. 转存分享文件（`sharepage/save`）

接口概览

请求体参数

请求示例

响应示例

关键响应字段

使用说明

8. 查询转存任务状态

接口概览

Query 参数