Overview
The NTQQFileApi class provides methods for uploading, downloading, and managing files, including images, videos, audio, and documents.
File Upload
uploadFile
Upload a file and get its metadata.
async uploadFile(
filePath: string,
elementType: ElementType = ElementType.PIC,
elementSubType: number = 0,
uploadGroupFile: boolean = true
): Promise<{
md5: string;
fileName: string;
path: string;
fileSize: number;
ext: string;
}>
elementType
ElementType
default:"ElementType.PIC"
Type of element (PIC, VIDEO, PTT, FILE, etc.)
Whether to upload as group file
Object containing file metadata:
md5: File MD5 hashfileName: File namepath: File pathfileSize: File size in bytesext: File extension
const fileInfo = await core.apis.FileApi.uploadFile(
'/path/to/image.png',
ElementType.PIC
);
console.log('MD5:', fileInfo.md5);
console.log('Size:', fileInfo.fileSize, 'bytes');
File Download
Download media from a message.
async downloadMedia(
msgId: string,
chatType: ChatType,
peerUid: string,
elementId: string,
thumbPath: string,
sourcePath: string,
timeout: number = 120000,
force: boolean = false
): Promise<string>
Message ID containing the media
Chat type (group/private)
Download timeout in milliseconds
Force re-download even if file exists
const filePath = await core.apis.FileApi.downloadMedia(
msg.msgId,
ChatType.KCHATTYPEGROUP,
'123456789',
element.elementId,
'',
'',
60000
);
console.log('Downloaded to:', filePath);
async downloadRawMsgMedia(
msg: RawMessage[]
): Promise<string[]>
Array of file paths to downloaded media
const messages = await core.apis.MsgApi.getMsgHistory(peer, '0', 10);
const files = await core.apis.FileApi.downloadRawMsgMedia(messages.msgList);
console.log(`Downloaded ${files.length} files`);
files.forEach(file => console.log(file));
async downloadFileForModelId(
peer: Peer,
modelId: string,
unknown: string,
timeout: number = 120000
): Promise<string>
downloadFileById
Download file by file ID.
async downloadFileById(
fileId: string,
fileSize: number = 1024576,
estimatedTime: number = (fileSize * 1000 / 1024576) + 5000
): Promise<string>
Expected file size in bytes
Estimated download time in milliseconds (auto-calculated)
File URLs
getFileUrl
Get download URL for a file.
async getFileUrl(
chatType: ChatType,
peer: string,
fileUUID?: string,
file10MMd5?: string,
timeout: number = 5000
): Promise<string>
Chat type (group/private)
File MD5 (for files < 10MB)
Request timeout in milliseconds
const url = await core.apis.FileApi.getFileUrl(
ChatType.KCHATTYPEGROUP,
'123456789',
fileElement.fileUuid
);
console.log('Download URL:', url);
getPttUrl
Get download URL for voice/audio file.
async getPttUrl(
peer: string,
fileUUID?: string,
timeout: number = 5000
): Promise<string>
getVideoUrl
Get playback URL for video.
async getVideoUrl(
peer: Peer,
msgId: string,
elementId: string
): Promise<string>
getVideoUrlPacket
Get video URL using packet API.
async getVideoUrlPacket(
peer: string,
fileUUID?: string,
timeout: number = 5000
): Promise<string>
Image URLs
getImageUrl
Get image URL from picture element.
async getImageUrl(element: PicElement): Promise<string>
Picture element from message
const picElement = msg.elements.find(e => e.picElement)?.picElement;
if (picElement) {
const imageUrl = await core.apis.FileApi.getImageUrl(picElement);
console.log('Image URL:', imageUrl);
}
File Search
searchForFile
Search for files by keywords.
async searchForFile(
keys: string[]
): Promise<SearchResultItem | undefined>
return
SearchResultItem | undefined
First matching search result
const result = await core.apis.FileApi.searchForFile(['document', 'pdf']);
if (result) {
console.log('Found file:', result.fileName);
console.log('File ID:', result.fileId);
}
File Utilities
copyFile
Copy a file to another location.
async copyFile(filePath: string, destPath: string)
getFileSize
Get size of a file.
async getFileSize(filePath: string): Promise<number>
const size = await core.apis.FileApi.getFileSize('/path/to/file.pdf');
console.log(`File size: ${(size / 1024 / 1024).toFixed(2)} MB`);
Complete Example: File Upload and Download
import { NapCatCore } from '@/napcat-core';
import { ChatType, ElementType } from '@/napcat-core/types';
async function handleFileOperations(core: NapCatCore) {
// Upload an image
const imageInfo = await core.apis.FileApi.uploadFile(
'/path/to/image.jpg',
ElementType.PIC
);
console.log('Uploaded image:');
console.log(' MD5:', imageInfo.md5);
console.log(' Size:', imageInfo.fileSize, 'bytes');
// Send the image in a message
const peer = {
chatType: ChatType.KCHATTYPEGROUP,
peerUid: '123456789',
};
const msg = await core.apis.MsgApi.sendMsg(peer, [{
picElement: {
md5HexStr: imageInfo.md5,
fileSize: imageInfo.fileSize,
sourcePath: imageInfo.path,
fileName: imageInfo.fileName,
}
}]);
// Later, download media from messages
const history = await core.apis.MsgApi.getMsgHistory(peer, '0', 10);
const mediaFiles = await core.apis.FileApi.downloadRawMsgMedia(
history.msgList
);
console.log(`\nDownloaded ${mediaFiles.length} media files:`);
mediaFiles.forEach((file, i) => {
console.log(` ${i + 1}. ${file}`);
});
// Search for files
const searchResult = await core.apis.FileApi.searchForFile(['report']);
if (searchResult) {
console.log('\nFound file:', searchResult.fileName);
// Download the found file
const downloadPath = await core.apis.FileApi.downloadFileById(
searchResult.fileId,
searchResult.fileSize
);
console.log('Downloaded to:', downloadPath);
}
}
// Usage
handleFileOperations(core).catch(console.error);
Notes
- File operations may have size limits imposed by QQ servers
- Large file downloads should use appropriate timeout values
- The RKey (resource key) is automatically managed for file URLs
- Some file operations require packet API to be enabled
- Downloaded files are typically stored in NTQQ’s cache directory
