开放平台总览

Disk.Top 开放平台

用 OAuth 2.0 + REST API 把 Disk.Top 云存储能力接入你的应用。

#快速导航

OAuth 2.0 概览
授权码模式 — Web / Wap
设备码模式 — CLI / TV / 扫码
权限范围 Scopes — 沙盒 vs 全盘
用户 API
文件 API
分享 API

#4 步接入

创建应用 在 /console — 拿 client_id + client_secret

跳转用户授权：

GET https://openapi.disk.top/oauth/authorize?client_id=YOUR_ID&redirect_uri=YOUR_CALLBACK&response_type=code&scope=user.read+files.app_data&state=xyz

用 code 兑 access_token：

POST https://openapi.disk.top/oauth/token
grant_type=authorization_code&code=...&client_id=...&client_secret=...&redirect_uri=...

带 Bearer 调 API：

curl -H "Authorization: Bearer ACCESS_TOKEN" https://openapi.disk.top/v1/user/info

#沙盒模型

默认 (files.app_data scope) 应用拿到用户网盘下的专属目录：/我的应用数据/<你的应用名>/。所有文件操作限制在沙盒内。

需要全盘访问请申请 files.read_all / files.write_all —— 用户授权时会看到敏感权限警告。

OAuth 2.0 概述

OAuth 2.0 Overview

Disk.Top supports three OAuth 2.0 grant types.

#1. Authorization Code Grant (Web)

Standard server-side flow with redirect_uri. Use for web/wap apps.

See Authorization Code Flow for details.

#2. Device Code Grant (CLI / TV)

For devices without a browser (CLI tools, Android TV, IoT). The device shows a user_code and verification_uri; user visits the URL on their phone, enters the code, and approves.

See Device Code Flow.

#3. Refresh Token

Standard grant_type=refresh_token — exchange a refresh_token for a new access_token. Refresh tokens rotate on each use.

POST https://openapi.disk.top/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=...&client_id=...&client_secret=...

#PKCE Support

All grants support PKCE (code_challenge / code_verifier). Recommended for mobile apps and SPAs where client_secret cannot be stored securely.

# Generate
code_verifier = base64url(random(32))
code_challenge = base64url(SHA256(code_verifier))

# In /oauth/authorize URL
&code_challenge=...&code_challenge_method=S256

# In /oauth/token request
&code_verifier=...

授权码模式

授权码模式（Authorization Code）

适用于 所有 5 类应用类型：Web、Mobile_web、Android、iOS、Desktop。

#通用流程

#Step 1：跳转用户到 /oauth/authorize

GET https://openapi.disk.top/oauth/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_CALLBACK
  &response_type=code
  &scope=user.read+files.app_data
  &state=RANDOM_STATE
  &code_challenge=...           # 可选 PKCE（推荐 mobile/desktop 必用）
  &code_challenge_method=S256

用户未登录 Disk.Top 时，平台会先 302 到登录页（cp.disk.top/#/auth/login?next=...），登录后自动跳回 authorize 页继续。

#Step 2：用户同意授权

用户看到授权页（列出本次申请的 scope），点击「允许」后 302 回 redirect_uri：

{redirect_uri}?code=AUTH_CODE&state=RANDOM_STATE

用户拒绝则返：

{redirect_uri}?error=access_denied&state=RANDOM_STATE

#Step 3：用 code 换 access_token

POST https://openapi.disk.top/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET   # 仅 web/server 类要传；mobile/desktop 必须用 PKCE 代替
&redirect_uri=YOUR_CALLBACK
&code_verifier=...                  # 若使用 PKCE

响应：

{
  "access_token": "Pc0yjnIrGqKr39YQY85i...",
  "refresh_token": "T_roVaOwg7X_NrSCm...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "user.read files.app_data"
}

#Step 4：用 access_token 调业务接口

curl -H "Authorization: Bearer Pc0yjnIrGq..." \
  https://openapi.disk.top/v1/user/info

#错误码

Error	含义
`invalid_client`	client_id / secret 不匹配
`invalid_grant`	code 过期、已使用，或 redirect_uri 不匹配
`invalid_redirect_uri`	redirect_uri 不在 app 白名单
`access_denied`	用户在授权页点拒绝
`unsupported_response_type`	response_type 必须是 `code`

#按应用类型接入

不同 application_type 在 redirect_uri 格式 和 client_secret 用法 上有差异。

#一、Web 应用

application_type=web
redirect_uri 必须 https://（localhost 例外可用 http://localhost）
后端持有 client_secret，code → token 直接传 secret
不需要 PKCE（但加上更安全）

redirect_uri = https://yourapp.com/oauth/callback

接入步骤：

在 console 创建 app，类型选 web，填入回调 URL
后端实现回调路由接收 code，调 /oauth/token 用 client_secret 换 token
token 存数据库（refresh 30d 有效）

#二、移动端 Web（mobile_web）

application_type=mobile_web
跟 web 一样必须 https://
通常配合 PWA / 单页 app 使用
建议用 PKCE 防止前端泄露 client_secret

redirect_uri = https://m.yourapp.com/oauth/callback

#三、Android 原生

application_type=android
redirect_uri 必须 custom scheme（反向域名 + :// 路径）
必须用 PKCE（不能保密 client_secret）

redirect_uri = com.yourcompany.yourapp:/oauth/callback

Android 实现：

AndroidManifest.xml 注册 intent-filter：

<activity android:name=".OAuthCallbackActivity">
  <intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="com.yourcompany.yourapp" android:host="oauth"/>
  </intent-filter>
</activity>

生成 PKCE pair：

val codeVerifier = base64Url(SecureRandom().nextBytes(32))
val codeChallenge = base64Url(SHA256(codeVerifier))

用系统浏览器（Custom Tab 推荐）打开 authorize URL
收到 callback intent，提取 code，POST /oauth/token 带上 code_verifier

#四、iOS 原生

application_type=ios
redirect_uri 必须 custom scheme 或 https Universal Link
必须用 PKCE

# Custom scheme
redirect_uri = com.yourcompany.yourapp:/oauth/callback

# 或 Universal Link
redirect_uri = https://yourapp.com/applinks/oauth

iOS 实现：

Info.plist 注册 URL Type：

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array><string>com.yourcompany.yourapp</string></array>
  </dict>
</array>

用 ASWebAuthenticationSession（iOS 12+）打开授权页
收到 callback，提取 code，调 /oauth/token 带 code_verifier

#五、桌面应用（Desktop）

application_type=desktop
redirect_uri 必须 loopback IP：http://127.0.0.1[:port] 或 http://localhost[:port]
必须用 PKCE

redirect_uri = http://127.0.0.1:51729/oauth/callback

桌面端实现：

App 启动随机端口本地 HTTP server 监听 /oauth/callback
生成 PKCE pair
用系统默认浏览器打开 authorize URL（不要嵌入 WebView）
收到 callback HTTP 请求，提取 code，关本地 server
后端进程或本地调 /oauth/token 换 token，token 存系统 keychain（macOS Keychain / Windows DPAPI / Linux libsecret）

#PKCE（推荐所有非 web 类型必用）

PKCE = Proof Key for Code Exchange (RFC 7636)。防止 code 在 redirect 过程中被窃取后重放。

生成方式：

code_verifier  = random 43-128 字符（A-Z a-z 0-9 - . _ ~）
code_challenge = base64url(sha256(code_verifier))     # method=S256

请求 authorize 时带 code_challenge + code_challenge_method=S256，换 token 时带 code_verifier。Disk.Top 服务端会校验 sha256(code_verifier) == code_challenge。

#refresh_token

token 过期后用 refresh：

POST /oauth/token
grant_type=refresh_token
&refresh_token=T_roVaOwg7X_NrSCm...
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET   # web/server 类要传

refresh_token 有效期 30 天。

#设备码模式

电视、IoT 等无浏览器设备见 oauth-device-code 文档。

设备码模式（CLI / TV）

Device Code Flow

For headless devices (CLI tools, Android TV, IoT) where a full browser-based OAuth flow is impractical.

#Step 1: Request a device code

POST https://openapi.disk.top/oauth/device-code
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&scope=user.read+files.app_data

Response:

{
  "device_code": "sHxGyZ9rEd73E6PYg2yEdWWps9evt_oTDOqzFcxQJRxsZEUk",
  "user_code": "8KXH-Y8R",
  "verification_uri": "https://openapi.disk.top/oauth/device",
  "verification_uri_complete": "https://openapi.disk.top/oauth/device?user_code=8KXH-Y8R",
  "qr_url": "https://api.qrserver.com/v1/create-qr-code/?size=240x240&data=...",
  "expires_in": 600,
  "interval": 5
}

#Step 2: Display to user

Show the user_code AND/OR QR code on your device. User visits verification_uri on their phone, enters the code, and approves.

#Step 3: Poll for token

POST https://openapi.disk.top/oauth/device-token
Content-Type: application/x-www-form-urlencoded

device_code=sHxG...&client_id=YOUR_CLIENT_ID

Possible responses:

{"error":"authorization_pending"} — keep polling (respect interval)
{"error":"access_denied"} — user denied; stop polling
{"error":"expired_token"} — device_code expired; restart
{"access_token": "...", "refresh_token": "...", ...} — success!

权限范围 (Scopes)

Scopes

Permissions your app requests at authorization time. Users see the exact list on the consent page.

#Default (Sandbox Model)

user.read — Read user profile (uid, username, email, avatar, VIP status)
files.app_data — Default sandbox. Read/write files within a dedicated directory /我的应用数据/<YourAppName>/ in the user's cloud. Cannot access user's other files.

These scopes give your app broader access. Users see warnings on the consent page.

files.read_all — Read all user files (across all directories)
files.write_all — Write/delete any user file
share.read — List all the user's shares
share.create — Create new shares on behalf of the user

#Best Practices

Request the minimum scopes you need. Users abandon apps that ask too much.
Use sandbox (files.app_data) unless you really need full-disk access.
New apps default to sandbox-only — broader scopes require admin review.
Users can revoke any time at disk.top/user/apps.

用户信息接口

获取当前 OAuth 授权用户的账号信息 / 容量 / 分享开关。

#用户基础信息

返回授权用户的 profile（含 uid、昵称、头像、VIP 状态、绑定的 OAuth client、本次授权 scope）。

#接口地址

https://openapi.disk.top/v1/user/info

#请求方式

GET

#请求参数

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`，scope 含 `user.read`

#请求示例

curl "https://openapi.disk.top/v1/user/info" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

#响应参数

字段	类型	说明
`data.uid`	int	用户 id
`data.username`	string	登录名
`data.nickname`	string	昵称
`data.email`	string	邮箱（脱敏）
`data.avatar_url`	string	头像 URL
`data.is_vip`	bool	是否 VIP
`data.vip_group`	int	VIP 等级（1-10）
`data.vip_expire_ts`	int	VIP 过期 unix ts，0=永久或非 VIP
`data.storage_quota_bytes`	int	总存储配额（字节）
`data.created_at_ts`	int	账号注册 unix ts
`data.oauth.client_id`	string	当前授权的 app client_id
`data.oauth.scopes`	string[]	本次授权实际生效的 scope 列表

#响应示例

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "uid": 17,
    "username": "dwtonline",
    "nickname": "jam",
    "email": "[email protected]",
    "avatar_url": "https://disk.top/uploads/upload/avatar/17_xxx.jpg",
    "is_vip": false,
    "vip_group": 3,
    "vip_expire_ts": 0,
    "storage_quota_bytes": 1610612736000,
    "created_at_ts": 1636115986,
    "oauth": {
      "client_id": "your_client_id",
      "scopes": ["user.read","files.app_data"]
    }
  }
}

#容量相关

返回当前用户的总配额 / 已用 / 剩余 / 使用百分比。常用在「我的空间」页面展示进度条。

#接口地址

https://openapi.disk.top/v1/user/quota

#请求方式

GET

#请求参数

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`，scope 含 `user.read`

#请求示例

curl "https://openapi.disk.top/v1/user/quota" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

#响应参数

字段	类型	说明
`data.total_bytes`	int	总配额（字节）
`data.used_bytes`	int	已用
`data.free_bytes`	int	剩余
`data.used_pct`	float	使用百分比（0-100）

#响应示例

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "total_bytes": 1610612736000,
    "used_bytes": 33691310918,
    "free_bytes": 1576921425082,
    "used_pct": 2.09
  }
}

#开启分享能力

激活当前用户的「创建分享」功能（每个新接入的 OAuth app 调用一次即可）。开启后才能调 /v1/share/* create 类接口。

#接口地址

https://openapi.disk.top/v1/user/share-enable

#请求方式

POST

#请求参数

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`，scope 含 `share.create`

#请求示例

curl -X POST "https://openapi.disk.top/v1/user/share-enable" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

#响应参数

字段	类型	说明
`data.enabled`	bool	true=已开启
`data.note`	string	说明文本

#响应示例

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "enabled": true,
    "note": "Share endpoints are now active."
  }
}

文件管理接口

OAuth 应用读写用户网盘文件。默认 scope files.app_data 只能读写沙盒目录 /我的应用数据/{AppName}/，files.write_all 可写全盘（需用户授权）。

上传协议：precreate（拿 upload_id + endpoint）→ 分块上传 → complete。Client 无需关心存储后端实现细节。

#列目录

列出沙盒（或全盘）某路径下的文件 + 子目录。

#接口地址

https://openapi.disk.top/v1/files

#请求方式

GET

#请求参数

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`path`	query	否	string	相对路径，默认 `/`。`files.app_data` scope 下 `/` 指沙盒根
`page`	query	否	int	页码，默认 1
`limit`	query	否	int	每页数量，默认 50，最大 200

#请求示例

curl -G "https://openapi.disk.top/v1/files" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "path=/" --data-urlencode "limit=20"

#响应参数

字段	类型	说明
`data.folders[].id`	int	文件夹 id
`data.folders[].name`	string	文件夹名
`data.files[].id`	int	文件 id
`data.files[].name`	string	原始名
`data.files[].size`	int	字节数
`data.files[].md5`	string	文件 md5
`data.total`	int	当前路径下总数

#响应示例

{
  "errno":0,"errmsg":"ok",
  "data":{
    "path":"/","folders":[{"id":5911,"name":"GPTGet"}],
    "files":[{"id":7280,"name":"chat-1.md","size":1024,"md5":"abc..."}],
    "total":2
  }
}

#搜索文件

按文件名 / 扩展名搜索。仅搜索沙盒（或全盘 if files.read_all）。

#接口地址

https://openapi.disk.top/v1/files/search

#请求方式

GET

#请求参数

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`q`	query	是	string	搜索关键词（匹配 origin_name）
`ext`	query	否	string	扩展名过滤（如 `mp4`）
`limit`	query	否	int	最多返回，默认 50

#请求示例

curl -G "https://openapi.disk.top/v1/files/search" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "q=chat"

#响应示例

{"errno":0,"data":{"files":[{"id":7280,"name":"chat-573.md","size":1024,"md5":"abc..."}],"total":1}}

#文件元信息

按 file_id 查文件详情（路径 / md5 / 大小 / 上传时间 / mime 等）。

#接口地址

https://openapi.disk.top/v1/files/{id}

#请求方式

GET

#请求参数

参数	位置	必填	说明
`Authorization`	header	是	Bearer
`id`	path	是	file_id

#响应示例

{
  "errno":0,
  "data":{
    "id":7280,"name":"chat-573.md","size":1024,
    "md5":"abc...","ext":"md","mime":"text/markdown",
    "path":"/我的应用数据/GPTGet/chat-573.md",
    "parent_folder":5911,
    "create_time":1779051234
  }
}

#文件下载

获取文件直链下载 URL（10 分钟内有效，已签名，可 Range 续传）。

#接口地址

https://openapi.disk.top/v1/files/{id}/download

#请求方式

GET

#请求参数

参数	位置	必填	说明
`Authorization`	header	是	Bearer
`id`	path	是	file_id

#响应参数

字段	类型	说明
`data.url`	string	临时直链 URL（已签名）
`data.expires_in`	int	直链有效秒数（默认 600）
`data.name`, `data.size`, `data.md5`	-	文件信息

#响应示例

{
  "errno":0,
  "data":{
    "url":"https://dl.disk-api.com/abc/file.mp4?sig=...&exp=...",
    "expires_in":600,
    "name":"demo.mp4","size":8388608,"md5":"abc..."
  }
}

#视频在线播放

返回视频 HLS / DASH 播放列表 URL（在线播放器用）。

#接口地址

https://openapi.disk.top/v1/files/{id}/stream

#请求方式

GET

#响应示例

{
  "errno":0,
  "data":{
    "stream_url":"https://dl.disk-api.com/hls/abc/master.m3u8?sig=...",
    "duration":1800,
    "qualities":[{"name":"1080p","url":"..."}],
    "expires_in":600
  }
}

#新建文件夹

在指定父目录下创建新文件夹。

#接口地址

https://openapi.disk.top/v1/files/folder

#请求方式

POST

#请求参数

参数	位置	必填	说明
`Authorization`	header	是	Bearer，scope 含 `files.app_data` 或 `files.write_all`
`parent_path`	body	否	父路径，默认 `/`（沙盒根）
`name`	body	是	新文件夹名

#请求示例

curl -X POST "https://openapi.disk.top/v1/files/folder" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "parent_path=/&name=Photos"

#响应示例

{"errno":0,"data":{"folder_id":5920,"name":"Photos","path":"/我的应用数据/GPTGet/Photos"}}

#重命名 / 移动 / 删除

批量操作（一次请求改多文件 / 多目录）。

#接口地址

https://openapi.disk.top/v1/files/manage

#请求方式

POST

#请求参数

参数	位置	必填	说明
`Authorization`	header	是	Bearer，scope `files.app_data` / `files.write_all`
`action`	body	是	`rename` / `move` / `copy` / `delete`
`file_ids`	body array	否	要操作的 file_id 列表
`folder_ids`	body array	否	要操作的 folder_id 列表
`dest_path`	body	move/copy 时	目标父路径
`new_name`	body	rename 时	新名

#请求示例

# 删除
curl -X POST "https://openapi.disk.top/v1/files/manage" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "action=delete&file_ids[]=7280&file_ids[]=7281"

# 重命名
curl -X POST "https://openapi.disk.top/v1/files/manage" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "action=rename&file_ids[]=7280&new_name=updated.md"

#响应示例

{"errno":0,"data":{"affected":2}}

#上传：precreate（秒传检测 + 拿 upload session）

上传第一步。提交 md5 + size，命中秒传直接返 file_id；否则返 upload_id 走分块上传。

#接口地址

https://openapi.disk.top/v1/files/upload/precreate

#请求方式

POST

#请求参数

参数	位置	必填	说明
`Authorization`	header	是	Bearer，scope 含 `files.app_data` / `files.write_all`
`parent_path`	body	否	父路径，默认 `/`（沙盒根）
`name`	body	是	文件名
`size`	body	是	字节数
`md5`	body	是	整文件 md5（小写 32 位 hex）
`content_type`	body	否	MIME，默认 `application/octet-stream`

#请求示例

curl -X POST "https://openapi.disk.top/v1/files/upload/precreate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "parent_path=/&name=movie.mp4&size=104857600&md5=5eb63bbbe01eeed093cb22bb8f5acdc3"

#响应参数

字段	类型	说明
`data.instant_upload`	bool	true=秒传命中，直接拿 `file_id`；false=走分块上传
`data.file_id`	int	秒传命中时返此字段
`data.upload_id`	string	非秒传时返，client 用此 ID 上传分块
`data.endpoint`	string	分块上传服务公网 URL（如 `https://openapi-upload.disk.top`）
`data.chunk_size`	int	分块字节数（client 切片用）
`data.total_parts`	int	应传分块数
`data.expires_in`	int	upload session 有效秒数（默认 86400）

#响应示例

{
  "errno":0,
  "data":{
    "instant_upload":false,
    "upload_id":"a747204b5517044b304fe07b649c6bdc",
    "endpoint":"https://openapi-upload.disk.top",
    "chunk_size":5242880,
    "total_parts":20,
    "expires_in":86400
  }
}

秒传命中：

{"errno":0,"data":{"instant_upload":true,"file_id":7266,"path":"/我的应用数据/GPTGet/movie.mp4","size":104857600}}

#上传：chunk（上传单个分块）

按 precreate 返的 chunk_size 切片，每片调用一次此接口（直接 POST 给 precreate 返的 endpoint）。

#接口地址

{endpoint}/u?upload_id={upload_id}&part_seq={N}

{endpoint} 取 precreate 返的值；{N} 从 1 开始递增。

#请求方式

POST

#请求参数

参数	位置	必填	说明
`upload_id`	query	是	precreate 返的值
`part_seq`	query	是	当前分块序号（1-based）
body	raw	是	当前分块字节（Content-Type: application/octet-stream）

#请求示例

# 第 1 片
dd if=movie.mp4 bs=5242880 count=1 skip=0 | \
  curl -X POST "https://openapi-upload.disk.top/u?upload_id=a747...&part_seq=1" \
    -H "Content-Type: application/octet-stream" --data-binary @-

# 第 N 片同理

#响应参数

字段	类型	说明
`data.part_seq`	int	已收到的分块序号
`data.etag`	string	该分块的 ETag（可选，部分场景为空）
`data.received_parts`	int	累计已收数
`data.total_parts`	int	总数

#响应示例

{"errno":0,"data":{"part_seq":1,"etag":"abc123...","size":5242880,"received_parts":1,"total_parts":20}}

#上传：查进度 / 已传分块（断点续传用）

查询已传分块，client 跳过已传的部分续传。

#接口地址

{endpoint}/u/{upload_id}/parts

#请求方式

GET

#响应参数

字段	类型	说明
`data.upload_id`	string	upload_id
`data.total_parts`	int	总应传
`data.received_parts`	int[]	已收 part_seq 列表（升序）
`data.progress`	float	进度百分比
`data.parts`	object	详细 part_seq → {part_number, etag, size} 映射

#响应示例

{
  "errno":0,
  "data":{
    "upload_id":"a747...",
    "total_parts":20,
    "received_parts":[1,2,3,5,6,7],
    "progress":35.0,
    "parts":{"1":{"part_number":1,"etag":"abc","size":5242880},"...":{}}
  }
}

#上传：complete（合并 + 写表）

所有分块上传完成后调此接口，服务端合并分块并入库，返 file_id。

#接口地址

{endpoint}/u/{upload_id}/complete

#请求方式

POST

#响应参数

字段	类型	说明
`data.file_id`	int	新文件 id
`data.path`	string	文件完整路径
`data.size`	int	字节数
`data.md5`	string	文件 md5

#响应示例

{
  "errno":0,
  "data":{
    "file_id":7280,
    "path":"/我的应用数据/GPTGet/movie.mp4",
    "size":104857600,
    "md5":"5eb63bbbe01eeed093cb22bb8f5acdc3"
  }
}

错误：

425 incomplete: N/M — 还缺片，调 /parts 查缺哪些续传
502 complete failed — 服务端错，重试或检查日志

#上传：abort（取消上传 + 清理）

主动取消上传，服务端释放对应分块资源。

#接口地址

{endpoint}/u/{upload_id}/abort

#请求方式

POST

#响应示例

{"errno":0,"data":{"ok":true}}

分享相关接口

操作 Disk.Top 公开分享（/s/{surl} 短链）。所有接口需 Authorization: Bearer {access_token}，scope: share.read 或 share.create（transfer 额外需 files.app_data 或 files.write_all）。

{surl} 是分享短链 code（如 8d2f3a），不是数据库 share_id。

如分享设置了提取码，先调此接口换 session 后续访问免传 pwd。

https://openapi.disk.top/v1/share/{surl}/verify-pwd

POST

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`surl`	path	是	string	分享 surl_code
`pwd`	body	是	string	4 位提取码

curl -X POST "https://openapi.disk.top/v1/share/8d2f3a/verify-pwd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "pwd=1234"

字段	类型	说明
`errno`	int	0=验证通过；非 0 错误
`data.verified`	bool	true

{"errno":0,"errmsg":"ok","data":{"verified":true}}

获取分享元信息（类型、是否需密码、过期时间、文件数等）。

https://openapi.disk.top/v1/share/{surl}/info

GET

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`surl`	path	是	string	分享 surl_code

curl "https://openapi.disk.top/v1/share/8d2f3a/info" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

字段	类型	说明
`data.surl`	string	短链 code
`data.type`	int	0=文件，1=文件夹
`data.need_pwd`	bool	是否需提取码
`data.expire_time`	int	过期 unix 时间戳，0=永不
`data.source_count`	int	文件数
`data.premium`	bool	是否会员专享

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "surl": "8d2f3a",
    "type": 1,
    "need_pwd": false,
    "expire_time": 0,
    "source_count": 5,
    "premium": false
  }
}

列出分享内的文件 / 子目录。文件夹分享按 path 浏览，文件分享直接返单文件。

https://openapi.disk.top/v1/share/{surl}/files

GET

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`surl`	path	是	string	分享 surl_code
`path`	query	否	string	文件夹分享内子路径，默认 `/`
`pwd`	query	视情况	string	提取码，若 need_pwd=true 必填

curl -G "https://openapi.disk.top/v1/share/8d2f3a/files" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "path=/" --data-urlencode "pwd=1234"

字段	类型	说明
`data.files[].id`	int	文件 id
`data.files[].name`	string	原始名
`data.files[].size`	int	字节数
`data.files[].ext`	string	扩展名
`data.files[].is_dir`	bool	是否目录

{
  "errno": 0,
  "errmsg": "ok",
  "data": {
    "files": [
      {"id": 12345, "name": "demo.mp4", "size": 8388608, "ext": "mp4", "is_dir": false},
      {"id": 12346, "name": "docs", "size": 0, "ext": "", "is_dir": true}
    ]
  }
}

把分享文件复制到当前 OAuth user 沙盒目录。

https://openapi.disk.top/v1/share/{surl}/transfer

POST

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}` (scope 含 `files.app_data` 或 `files.write_all`)
`surl`	path	是	string	分享 surl_code
`file_ids`	body array	是	int[]	要转存的文件 id 列表
`dest_path`	body	否	string	目标路径（沙盒内相对路径，默认 `/`）
`pwd`	body	视情况	string	提取码

curl -X POST "https://openapi.disk.top/v1/share/8d2f3a/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "file_ids[]=12345&dest_path=/Saved&pwd=1234"

字段	类型	说明
`data.transferred`	int	实际转存成功数
`data.file_ids`	int[]	新建的 store_id 列表

{"errno":0,"errmsg":"ok","data":{"transferred":1,"file_ids":[7890]}}

返回分享视频文件的 HLS / 直接流 URL（在线播放用，10 分钟内有效）。

https://openapi.disk.top/v1/share/{surl}/stream

GET

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`surl`	path	是	string	分享 surl_code
`fid`	query	是	int	视频文件 id
`pwd`	query	视情况	string	提取码

字段	类型	说明
`data.stream_url`	string	HLS 主播放列表 URL
`data.duration`	int	视频时长（秒）
`data.qualities`	array	可选清晰度列表
`data.expires_in`	int	直链有效秒数

{
  "errno":0,
  "data":{
    "stream_url":"https://dl.disk-api.com/hls/abc/master.m3u8?sig=...",
    "duration":1800,
    "qualities":[{"name":"1080p","url":"..."}],
    "expires_in":600
  }
}

返回视频元数据（时长、分辨率、编码、封面）— 用于 player 初始化或缩略图展示。

https://openapi.disk.top/v1/share/{surl}/video-meta

GET

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`surl`	path	是	string	分享 surl_code
`fid`	query	是	int	视频文件 id

{
  "errno":0,
  "data":{
    "duration":1800,
    "width":1920,
    "height":1080,
    "codec":"h264",
    "bitrate":2500000,
    "cover_url":"https://s3-wnm.disk-api.com/.../cover.jpg"
  }
}

获取分享文件的临时直链下载 URL（10 分钟内有效，已签名，免登录直接下载）。

https://openapi.disk.top/v1/share/{surl}/download

GET

参数	位置	必填	类型	说明
`Authorization`	header	是	string	`Bearer {access_token}`
`surl`	path	是	string	分享 surl_code
`fid`	query	否	int	文件 id；不传则用分享根文件（仅单文件分享有效）
`pwd`	query	视情况	string	提取码

curl -G "https://openapi.disk.top/v1/share/8d2f3a/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "fid=12345" \
  --data-urlencode "pwd=1234"

字段	类型	说明
`data.file_id`	int	文件 id
`data.name`	string	原始名
`data.size`	int	字节数
`data.url`	string	临时直链 URL（已签名）
`data.expires_in`	int	直链有效秒数（默认 600）

{
  "errno":0,
  "data":{
    "file_id":12345,
    "name":"demo.mp4",
    "size":8388608,
    "url":"https://api.disk.top/v1/internal/openapi/share-download/8d2f3a/12345?ts=1779051234&sig=ab12c3...",
    "expires_in":600
  }
}

errno	含义
`invalid_surl`	surl 解码失败
`share_not_found`	分享不存在或已删除
`pwd_required_or_wrong`	提取码缺失或错误
`file_not_found`	fid 文件不存在

开放平台总览

Disk.Top 开放平台

#快速导航

#4 步接入

#沙盒模型

OAuth 2.0 概述

OAuth 2.0 Overview

#1. Authorization Code Grant (Web)

#2. Device Code Grant (CLI / TV)

#3. Refresh Token

#PKCE Support

授权码模式

授权码模式（Authorization Code）

#通用流程

#Step 1：跳转用户到 /oauth/authorize

#Step 2：用户同意授权

#Step 3：用 code 换 access_token

#Step 4：用 access_token 调业务接口

#错误码

#按应用类型接入

#一、Web 应用

#二、移动端 Web（mobile_web）

#三、Android 原生

#四、iOS 原生

#五、桌面应用（Desktop）

#PKCE（推荐所有非 web 类型必用）

#refresh_token

#设备码模式

设备码模式（CLI / TV）

Device Code Flow

#Step 1: Request a device code

#Step 2: Display to user

#Step 3: Poll for token

权限范围 (Scopes)

Scopes

#Default (Sandbox Model)

#Sensitive (Explicit Consent Required)

#Best Practices

用户信息接口

用户信息接口

#用户基础信息

#接口地址

#请求方式

#请求参数

#请求示例

#响应参数

#响应示例

#容量相关

#接口地址

#请求方式

#请求参数

#请求示例

#响应参数

#响应示例

#开启分享能力

#接口地址

#请求方式

#请求参数

#请求示例

#响应参数

#响应示例

文件管理接口

文件管理接口

#列目录

#接口地址

#请求方式

#请求参数

#请求示例

#响应参数

#响应示例

#搜索文件

#接口地址

#请求方式

#请求参数

#请求示例

#响应示例

#文件元信息

#接口地址

#请求方式

#请求参数