The Upload class provides methods for uploading various types of files to VK including photos, videos, documents, audio files, and more.
Constructor
import { Upload } from 'vk-io';
const upload = new Upload({
api: vk.api
});
Typically, you don’t need to instantiate Upload directly. Use vk.upload from the VK instance instead.
Parameters
Configuration options for the Upload instance.Show IUploadOptions Properties
API instance for making VK API calls.
Custom HTTPS agent for upload requests.
Timeout in milliseconds for upload operations.
Photo Upload Methods
photoAlbum()
Uploads photos to a VK album.
const photos = await vk.upload.photoAlbum({
album_id: 123,
source: {
value: 'path/to/photo.jpg'
}
});
Photo file source (path, URL, Buffer, or Stream).
Community ID (if uploading to community album).
Photo caption/description.
returns
Promise<PhotoAttachment[]>
Array of uploaded photo attachments (max 5 photos).
wallPhoto()
Uploads a photo to be posted on a wall.
const photo = await vk.upload.wallPhoto({
source: {
value: 'path/to/photo.jpg'
}
});
Uploaded photo attachment.
messagePhoto()
Uploads a photo to be sent in a message.
const photo = await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: 'path/to/photo.jpg'
}
});
await vk.api.messages.send({
peer_id: 123,
attachment: photo,
random_id: 0
});
Peer ID for the conversation.
Uploaded photo attachment ready to send in messages.
ownerPhoto()
Uploads a profile or community cover photo.
const result = await vk.upload.ownerPhoto({
owner_id: -123, // Negative for community
source: {
value: 'path/to/photo.jpg'
}
});
Owner ID (negative for community).
Upload result with photo URLs and hash.
URL to the uploaded photo.
URL to the small version.
Post ID if posted to wall.
chatPhoto()
Uploads a chat conversation photo.
const result = await vk.upload.chatPhoto({
chat_id: 1,
source: {
value: 'path/to/photo.jpg'
}
});
Result with message_id and chat information.
marketPhoto()
Uploads a photo for a market product.
const photo = await vk.upload.marketPhoto({
group_id: 123,
source: {
value: 'path/to/product.jpg'
}
});
1 if this is the main photo.
Uploaded market photo attachment.
marketAlbumPhoto()
Uploads a photo for a market collection.
const photo = await vk.upload.marketAlbumPhoto({
group_id: 123,
source: {
value: 'path/to/album-cover.jpg'
}
});
Uploaded album photo attachment.
groupCover()
Uploads a community cover photo.
const cover = await vk.upload.groupCover({
group_id: 123,
source: {
value: 'path/to/cover.jpg'
}
});
Object with array of cover images in different sizes.
Video Upload Methods
video()
Uploads a video file.
const video = await vk.upload.video({
name: 'My Video',
description: 'Video description',
source: {
value: 'path/to/video.mp4'
}
});
External video URL (YouTube, Vimeo, etc.).
1 to publish on wall after upload.
Uploaded video attachment.
Document Upload Methods
document()
Uploads a document file.
const doc = await vk.upload.document({
title: 'Document.pdf',
source: {
value: 'path/to/document.pdf'
}
});
returns
Promise<DocumentAttachment>
Uploaded document attachment.
wallDocument()
Uploads a document for a wall post.
const doc = await vk.upload.wallDocument({
source: {
value: 'path/to/file.pdf'
}
});
Same parameters as document() method.
returns
Promise<DocumentAttachment>
Uploaded document attachment.
messageDocument()
Uploads a document for a message.
const doc = await vk.upload.messageDocument({
peer_id: 123,
source: {
value: 'path/to/file.zip'
}
});
await vk.api.messages.send({
peer_id: 123,
attachment: doc,
random_id: 0
});
returns
Promise<DocumentAttachment>
Uploaded document attachment.
Audio Upload Methods
audio()
Uploads an audio file.
const audio = await vk.upload.audio({
title: 'Song Title',
artist: 'Artist Name',
source: {
value: 'path/to/song.mp3'
}
});
Uploaded audio attachment.
audioMessage()
Uploads a voice message.
const voiceMessage = await vk.upload.audioMessage({
peer_id: 123,
source: {
value: 'path/to/voice.ogg'
}
});
await vk.api.messages.send({
peer_id: 123,
attachment: voiceMessage,
random_id: 0
});
Audio file source (OGG format recommended).
returns
Promise<AudioMessageAttachment>
Uploaded voice message attachment.
Stories Upload Methods
storiesPhoto()
Uploads a photo story.
const story = await vk.upload.storiesPhoto({
link_text: 'learn_more',
link_url: 'https://example.com',
source: {
value: 'path/to/story.jpg'
}
});
Community ID (for community stories).
User IDs who can view the story.
JSON with clickable stickers.
Uploaded story attachment.
storiesVideo()
Uploads a video story.
const story = await vk.upload.storiesVideo({
link_text: 'learn_more',
link_url: 'https://example.com',
source: {
value: 'path/to/story.mp4'
}
});
Same parameters as storiesPhoto() but for video files.
Uploaded video story attachment.
Other Upload Methods
documentGraffiti()
Uploads a graffiti image as a document.
const graffiti = await vk.upload.documentGraffiti({
group_id: 123,
source: {
value: 'path/to/graffiti.png'
}
});
returns
Promise<GraffitiAttachment>
Uploaded graffiti attachment.
messageGraffiti()
Uploads a graffiti image for messages.
const graffiti = await vk.upload.messageGraffiti({
peer_id: 123,
source: {
value: 'path/to/graffiti.png'
}
});
returns
Promise<GraffitiAttachment>
Uploaded graffiti attachment for messages.
pollPhoto()
Uploads a photo for a poll.
const photo = await vk.upload.pollPhoto({
owner_id: 123,
source: {
value: 'path/to/photo.jpg'
}
});
returns
Promise<Record<string, any>>
Uploaded poll photo data.
Upload Sources
All upload methods accept various source types:
File Path
await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: '/path/to/photo.jpg'
}
});
URL
await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: 'https://example.com/photo.jpg'
}
});
Buffer
import fs from 'fs';
const buffer = fs.readFileSync('photo.jpg');
await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: buffer
}
});
Stream
import fs from 'fs';
const stream = fs.createReadStream('photo.jpg');
await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: stream
}
});
Multiple Files
// Upload up to 5 photos to album
const photos = await vk.upload.photoAlbum({
album_id: 123,
source: {
values: [
{ value: 'photo1.jpg' },
{ value: 'photo2.jpg' },
{ value: 'photo3.jpg' }
]
}
});
await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: buffer,
filename: 'custom-name.jpg',
contentType: 'image/jpeg',
contentLength: buffer.length
}
});
Examples
Upload and Send Photo
import { VK } from 'vk-io';
const vk = new VK({ token: process.env.VK_TOKEN });
const photo = await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: 'path/to/photo.jpg'
}
});
await vk.api.messages.send({
peer_id: 123,
message: 'Check out this photo!',
attachment: photo,
random_id: 0
});
Upload Multiple Photos to Album
const photos = await vk.upload.photoAlbum({
album_id: 123,
caption: 'My vacation photos',
source: {
values: [
{ value: 'photo1.jpg' },
{ value: 'photo2.jpg' },
{ value: 'photo3.jpg' },
{ value: 'photo4.jpg' },
{ value: 'photo5.jpg' }
]
}
});
console.log(`Uploaded ${photos.length} photos`);
Upload from URL
const photo = await vk.upload.wallPhoto({
source: {
value: 'https://picsum.photos/800/600'
},
caption: 'Random photo from URL'
});
await vk.api.wall.post({
owner_id: -123,
message: 'Check this out!',
attachments: photo.toString()
});
Upload and Send Document
const doc = await vk.upload.messageDocument({
peer_id: 123,
title: 'Important Document.pdf',
source: {
value: 'path/to/document.pdf'
}
});
await vk.api.messages.send({
peer_id: 123,
message: 'Here is the document you requested',
attachment: doc,
random_id: 0
});
Upload Voice Message
const voiceMessage = await vk.upload.audioMessage({
peer_id: 123,
source: {
value: 'path/to/recording.ogg'
}
});
await vk.api.messages.send({
peer_id: 123,
attachment: voiceMessage,
random_id: 0
});
Upload Video with Details
const video = await vk.upload.video({
name: 'My Awesome Video',
description: 'This is a great video!',
is_private: 0,
wallpost: 1,
source: {
value: 'path/to/video.mp4'
}
});
console.log('Video uploaded:', video.toString());
Error Handling
import { VK, UploadError } from 'vk-io';
const vk = new VK({ token: process.env.VK_TOKEN });
try {
const photo = await vk.upload.messagePhoto({
peer_id: 123,
source: {
value: 'nonexistent.jpg'
}
});
} catch (error) {
if (error instanceof UploadError) {
console.error(`Upload error: ${error.message}`);
console.error(`Error code: ${error.code}`);
}
}
Best Practices
File Format Support:
- Photos: JPG, PNG, GIF (max 50MB)
- Videos: MP4, AVI, MOV (max 6GB for regular users)
- Audio: MP3, OGG (for voice messages)
- Documents: Any format (max 200MB)
Upload Timeouts: Large files may take time to upload. Increase uploadTimeout if needed:const vk = new VK({
token: process.env.VK_TOKEN,
uploadTimeout: 60000 // 60 seconds
});
Attachment Strings: Convert attachments to strings for API calls:const photo = await vk.upload.messagePhoto({ /* ... */ });
// Use toString() or template literal
await vk.api.messages.send({
attachment: photo.toString(), // or `${photo}`
// ...
});