File API

NTQQFileApi methods for file upload, download, and management

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;
}>

filePath · string · required

Path to file to upload

elementType · ElementType · default: "ElementType.PIC"

Type of element (PIC, VIDEO, PTT, FILE, etc.)

elementSubType · number · default: "0"

Element subtype

uploadGroupFile · boolean · default: "true"

Whether to upload as group file

return · object

Object containing file metadata:

• md5: File MD5 hash
• fileName: File name
• path: File path
• fileSize: File size in bytes
• ext: File extension

Example:

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

downloadMedia

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>

msgId · string · required

Message ID containing the media

chatType · ChatType · required

Chat type (group/private)

peerUid · string · required

Peer UID

elementId · string · required

Element ID of the media

thumbPath · string · required

Thumbnail path

sourcePath · string · required

Source file path

timeout · number · default: "120000"

Download timeout in milliseconds

force · boolean · default: "false"

Force re-download even if file exists

return · string

Path to downloaded file

Example:

const filePath = await core.apis.FileApi.downloadMedia(
  msg.msgId,
  ChatType.KCHATTYPEGROUP,
  '123456789',
  element.elementId,
  '',
  '',
  60000
);

console.log('Downloaded to:', filePath);

downloadRawMsgMedia

Download all media elements from raw messages.

async downloadRawMsgMedia(
  msg: RawMessage[]
): Promise<string[]>

msg · RawMessage[] · required

Array of raw messages

return · string[]

Array of file paths to downloaded media

Example:

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));

downloadFileForModelId

Download file using model ID.

async downloadFileForModelId(
  peer: Peer,
  modelId: string,
  unknown: string,
  timeout: number = 120000
): Promise<string>

peer · Peer · required

Peer object

modelId · string · required

File model ID

unknown · string · required

Additional parameter

timeout · number · default: "120000"

Timeout in milliseconds

return · string

Downloaded file path

downloadFileById

Download file by file ID.

async downloadFileById(
  fileId: string,
  fileSize: number = 1024576,
  estimatedTime: number = (fileSize * 1000 / 1024576) + 5000
): Promise<string>

fileId · string · required

File ID to download

fileSize · number · default: "1024576"

Expected file size in bytes

estimatedTime · number

Estimated download time in milliseconds (auto-calculated)

return · string

Downloaded file path

File URLs

getFileUrl

Get download URL for a file.

async getFileUrl(
  chatType: ChatType,
  peer: string,
  fileUUID?: string,
  file10MMd5?: string,
  timeout: number = 5000
): Promise<string>

chatType · ChatType · required

Chat type (group/private)

peer · string · required

Peer ID

fileUUID · string

File UUID

file10MMd5 · string

File MD5 (for files < 10MB)

timeout · number · default: "5000"

Request timeout in milliseconds

return · string

File download URL

Example:

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>

peer · string · required

Peer ID

fileUUID · string

File UUID

timeout · number · default: "5000"

Request timeout

return · string

PTT (voice) file URL

getVideoUrl

Get playback URL for video.

async getVideoUrl(
  peer: Peer,
  msgId: string,
  elementId: string
): Promise<string>

peer · Peer · required

Peer object

msgId · string · required

Message ID

elementId · string · required

Video element ID

return · string

Video playback URL

getVideoUrlPacket

Get video URL using packet API.

async getVideoUrlPacket(
  peer: string,
  fileUUID?: string,
  timeout: number = 5000
): Promise<string>

peer · string · required

Peer ID

fileUUID · string

File UUID

timeout · number · default: "5000"

Request timeout

Image URLs

getImageUrl

Get image URL from picture element.

async getImageUrl(element: PicElement): Promise<string>

element · PicElement · required

Picture element from message

return · string

Image URL

Example:

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>

keys · string[] · required

Array of search keywords

return · SearchResultItem | undefined

First matching search result

Example:

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)

filePath · string · required

Source file path

destPath · string · required

Destination file path

getFileSize

Get size of a file.

async getFileSize(filePath: string): Promise<number>

filePath · string · required

Path to file

return · number

File size in bytes

Example:

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