onebot11

Appearance

文件相关API ​

获取群文件资源链接 ​

  • get_group_file_url (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "file_id": "abcdefg",
  "busid": 102 // napcat和lagrange废弃了这个字段
}
点击查看响应示例数据
json
{
  "url": "http://example.com/file"
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
file_idstring-文件 ID，从 get_group_root_files 或 get_group_files_by_folder 获取
busidnumber-文件类型，从 get_group_root_files 或 get_group_files_by_folder 获取

温馨提示

busid 在 NapCat 和 Lagrange 中被废弃

响应数据 ​

字段名数据类型说明
urlstring文件下载链接

获取私聊文件资源链接 ​

  • get_private_file_url (gocq拓展)
点击查看请求示例数据
json
{
  "user_id": 123456789,
  "file_id": "abcdefg",
  "busid": 102
}
点击查看NapCat请求示例数据
json
{
  "file_id": "abcdefg"
}
点击查看Lagrange请求示例数据
json
{
  "user_id": 123456789,
  "file_id": "abcdefg",
  "file_hash": "abcdefg" // 可选: 文件 Hash
}
点击查看响应示例数据
json
{
  "url": "http://example.com/file"
}

参数 ​

字段名数据类型默认值说明
user_idnumber-好友 QQ 号
file_idstring-文件 ID
busidnumber-文件类型
  • NapCat:
字段名数据类型默认值说明
file_idstring-文件 ID
  • Lagrange:
字段名数据类型默认值说明
user_idnumber-好友 QQ 号
file_idstring-文件 ID
file_hashstring-可选 文件 Hash

响应数据 ​

字段名数据类型说明
urlstring文件下载链接

上传群文件 ​

  • upload_group_file (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "file": "D:/file.txt",
  "name": "file.txt",
  "folder": "/"
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
filestring-本地文件路径
namestring-储存名称
folderstring-父目录ID

注意

在不提供 folder 参数的情况下默认上传到根目录

只能上传本地文件, 需要上传 http 文件的话请先调用 download_file API 下载

  • Lagrange:

    • file 仅支持 文件路径 一种方式，不支持前缀 file:// 这种路径

  • NapCat:

字段名数据类型默认值说明
group_idnumber-群号
filestring-支持 file:// base64 url 文件路径 四种方式
namestring-储存名称
folderstring-可选 父目录ID 与 folder_id 必须二选一
folder_idstring-可选 父目录ID 与 folder 必须二选一

响应数据 ​

提示

该 API 没有响应数据

获取群文件系统信息 ​

  • get_group_file_system_info (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789
}
点击查看响应示例数据
json
{
  "file_count": 10,
  "limit_count": 100,
  "used_space": 1024,
  "total_space": 10240
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号

响应数据 ​

字段名数据类型说明
file_countnumber文件总数
limit_countnumber文件上限
used_spacenumber已使用空间
total_spacenumber空间上限

获取群根目录文件列表 ​

  • get_group_root_files (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789
}
点击查看响应示例数据
json
{
  "files": [
    {
      "group_id": 123456789,
      "file_id": "abcdefg",
      "file_name": "file.txt",
      "busid": 102,
      "file_size": 1024,
      "upload_time": 1595294844,
      "dead_time": 0,
      "modify_time": 1595294844,
      "download_times": 0,
      "uploader": 123456789,
      "uploader_name": "上传者昵称"
    }
  ],
  "folders": [
    {
      "group_id": 123456789,
      "folder_id": "abcdefg",
      "folder_name": "文件夹",
      "create_time": 1595294844,
      "creator": 123456789,
      "creator_name": "创建者昵称",
      "total_file_count": 10
    }
  ]
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号

响应数据 ​

字段名数据类型说明
filesFile[]文件列表
foldersFolder[]文件夹列表

获取群子目录文件列表 ​

  • get_group_files_by_folder (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 0,
  "folder_id": "string", 
  "folder": "string",
  "file_count": 50 // 可选: 一次性获取的文件数量
}
点击查看NapCat请求示例数据
json
{
  "group_id": 123456789,
  "folder_id": "abcdefg"
}
点击查看响应示例数据
json
{
  "files": [
    {
      "group_id": 123456789,
      "file_id": "abcdefg",
      "file_name": "file.txt",
      "busid": 102,
      "file_size": 1024,
      "upload_time": 1595294844,
      "dead_time": 0,
      "modify_time": 1595294844,
      "download_times": 0,
      "uploader": 123456789,
      "uploader_name": "上传者昵称"
    }
  ],
  "folders": [
    {
      "group_id": 123456789,
      "folder_id": "abcdefg",
      "folder_name": "文件夹",
      "create_time": 1595294844,
      "creator": 123456789,
      "creator_name": "创建者昵称",
      "total_file_count": 10
    }
  ]
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
folder_idstring-文件夹 ID，从 get_group_root_files 获取
  • NapCat:
字段名数据类型默认值说明
group_idnumber-群号
folder_idstring-和 folder 二选一
folderstring-和 folder_id 二选一
file_countnumber50可选: 一次性获取的文件数量

响应数据 ​

字段名数据类型说明
filesFile[]文件列表
foldersFolder[]文件夹列表

删除群文件 ​

  • delete_group_file (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "file_id": "abcdefg",
  "busid": 102
}
点击查看NapCat响应示例数据
json
{
  "result": 0, // 0: 成功, 1: 失败
  "errMsg": "string", // 错误信息
  "transGroupFileResult": { // 群文件删除结果
    "result": { // 删除结果
      "retCode": 0, // 0: 成功, 1: 失败
      "retMsg": "string", // 错误信息
      "clientWording": "string" // 客户端提示
    },
    "successFileIdList": [
      "string" // 成功删除的文件ID列表
    ],
    "failFileIdList": [
      "string" // 删除失败的文件ID列表
    ]
  }
}
点击查看Lagrange响应示例数据
json
{
  "msg": "string", // 操作结果
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
file_idstring-文件 ID，从 get_group_root_files 或 get_group_files_by_folder 获取
busidnumber-文件类型，从 get_group_root_files 或 get_group_files_by_folder 获取

温馨提示

busid 在 NapCat 和 Lagrange 中被废弃

响应数据 ​

提示

该 API 没有响应数据

  • NapCat: 请参考上方 NapCat 的响应数据
  • Lagrange: 请参考上方 Lagrange 的响应数据

创建群文件文件夹 ​

  • create_group_file_folder (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "name": "文件夹", // 注意napcat是 folder_name
  "parent_id": "/" // tx不允许在非根目录创建文件夹了，该接口只能在根目录下创建文件夹
}
点击查看NapCat响应示例数据
json
{
  "result": { // 创建结果
    "retCode": 0, // 0: 成功, 1: 失败
    "retMsg": "string", // 错误信息
    "clientWording": "string" // 客户端提示
  },
  "groupItem": { // 群文件夹信息
    "peerId": "string", // 群号
    "type": 0, // 0: 文件夹, 1: 文件
    "folderInfo": { // 文件夹信息
      "folderId": "string", // 文件夹ID
      "parentFolderId": "string", // 父文件夹ID
      "folderName": "string", // 文件夹名称
      "createTime": 0, // 创建时间
      "modifyTime": 0, // 修改时间
      "createUin": "string", // 创建者ID
      "creatorName": "string", // 创建者昵称
      "totalFileCount": 0, // 文件总数
      "modifyUin": "string", // 修改者ID
      "modifyName": "string", // 修改者昵称
      "usedSpace": "string" // 已使用空间
    },
    "fileInfo": "string" // 文件信息
  }
}
点击查看Lagrange响应示例数据
json
{
  "msg": "string", // 操作结果
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
namestring-文件夹名称
parent_idstring/父目录 ID，/ 表示根目录
  • NapCat:
字段名数据类型默认值说明
group_idnumber-群号
folder_namestring-文件夹名称
  • Lagrange:
字段名数据类型默认值说明
group_idnumber-群号
namestring-文件夹名称

响应数据 ​

提示

该 API 没有响应数据

  • NapCat: 请参考上方 NapCat 的响应数据
  • Lagrange: 请参考上方 Lagrange 的响应数据

删除群文件文件夹 ​

注意

该 API 在 Lagrange 中为 delete_group_file_folder

  • delete_group_folder (gocq拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "folder_id": "abcdefg"
}
点击查看NapCat响应示例数据
json
{
  "retCode": 0, // 0: 成功, 1: 失败
  "retMsg": "string", // 错误信息
  "clientWording": "string" // 客户端提示
}
点击查看Lagrange响应示例数据
json
{
  "msg": "string", // 操作结果
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
folder_idstring-文件夹 ID，从 get_group_root_files 获取

响应数据 ​

提示

该 API 没有响应数据

  • NapCat: 请参考上方 NapCat 的响应示例数据
  • Lagrange: 请参考上方 Lagrange 的响应示例数据

上传私聊文件 ​

  • upload_private_file (gocq拓展)
点击查看请求示例数据
json
{
  "user_id": 123456789,
  "file": "D:/file.txt",
  "name": "file.txt"
}

参数 ​

字段名数据类型默认值说明
user_idnumber-好友 QQ 号
filestring-本地文件路径
namestring-上传后的文件名，若不指定则为上传前的文件名

注意

只能上传本地文件, 需要上传 http 文件的话请先调用 download_file API 下载

  • Lagrange:

    • file 仅支持 文件路径 一种方式，不支持前缀 file:// 这种路径

  • NapCat:

字段名数据类型默认值说明
user_idnumber-好友 QQ 号
filestring-支持 file:// base64 url 文件路径 四种方式
namestring-上传后的文件名，若不指定则为上传前的文件名

响应数据 ​

提示

该 API 没有响应数据

文件对象类型 ​

File ​

字段名数据类型说明
group_idnumber (int32)群号
file_idstring文件ID
file_namestring文件名
busidnumber (int32)文件类型
file_sizenumber (int64)文件大小
upload_timenumber (int64)上传时间
dead_timenumber (int64)过期时间，永久文件为0
modify_timenumber (int64)最后修改时间
download_timesnumber (int32)下载次数
uploadernumber (int64)上传者ID
uploader_namestring上传者名字

Folder ​

字段名数据类型说明
group_idnumber (int32)群号
folder_idstring文件夹ID
folder_namestring文件名
create_timenumber (int64)创建时间
creatornumber (int64)创建者
creator_namestring创建者名字
total_file_countnumber (int32)子文件数量

上传图片 ​

  • upload_image (Lagrange拓展)
点击查看请求示例数据
json
{
  "file": "D:/image.jpg"
}
点击查看响应示例数据
json
{
  "file": "图片文件名",
  "url": "图片URL"
}

参数 ​

字段名数据类型默认值说明
filestring-本地文件路径

响应数据 ​

字段名数据类型说明
filestring图片文件名
urlstring图片URL

移动群文件 ​

  • move_group_file (社区拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "file_id": "abcdefg",
  "folder_id": "/"
}
点击查看响应示例数据
json
{
  "success": true
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
file_idstring-文件 ID，从 get_group_root_files 或 get_group_files_by_folder 获取
folder_idstring-目标文件夹 ID，根目录为 /

响应数据 ​

字段名数据类型说明
successboolean是否移动成功

重命名群文件文件夹 ​

  • rename_group_file_folder (Lagrange拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "folder_id": "abcdefg",
  "new_name": "新文件夹名称"
}
点击查看响应示例数据
json
{
  "success": true
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
folder_idstring-文件夹 ID，从 get_group_root_files 或 get_group_files_by_folder 获取
new_namestring-新文件夹名称

响应数据 ​

字段名数据类型说明
successboolean是否重命名成功

转发群文件 ​

  • trans_group_file (NapCat拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "file_id": "file_id"
}
点击查看响应示例数据
json
{
  "ok": true
}

参数 ​

字段名数据类型默认值说明
group_idnumber-源群号
file_idstring-要转发的文件ID

响应数据 ​

字段名数据类型说明
okboolean转发成功

重命名群文件 ​

  • rename_group_file (NapCat拓展)
点击查看请求示例数据
json
{
  "group_id": 123456789,
  "file_id": "file_id",
  "current_parent_directory": "当前父目录",
  "new_name": "新文件名.txt"
}
点击查看响应示例数据
json
{
  "ok": true
}

参数 ​

字段名数据类型默认值说明
group_idnumber-群号
file_idstring-文件ID
current_parent_directorystring-当前父目录
new_namestring-新的文件名

响应数据 ​

字段名数据类型说明
okboolean重命名成功

获取文件 ​

  • get_file (NapCat拓展)
点击查看请求示例数据
json
{
  "file": "file_id",
  "file_id": "file_id"
}
点击查看响应示例数据
json
{
  "file": "path/to/file",
  "url": "file_url",
  "file_size": "file_size",
  "file_name": "file_name",
  "base64": "base64://..."
}

参数 ​

字段名数据类型默认值说明
filestring-文件ID
file_idstring-文件ID

响应数据 ​

字段名数据类型说明
filestring文件路径
urlstring文件 URL
file_sizestring文件大小
file_namestring文件名
base64string文件 base64 编码