Documentation Index
Fetch the complete documentation index at: https://mintlify.com/NapNeko/NapCatQQ/llms.txt
Use this file to discover all available pages before exploring further.
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
