npm install imgurVersion 2 of the imgur api drops automatic support for filesystem usage. For uploading files from a filesystem, please see the examples using createReadStream.
// ESModule syntax
import { ImgurClient } from 'imgur';
// CommonJS syntax
const { ImgurClient } = require('imgur');
// browser script include
const client = new imgur({ clientId: env.CLIENT_ID });
// if you already have an access token acquired
const client = new ImgurClient({ accessToken: process.env.ACCESS_TOKEN });
// or your client ID
const client = new ImgurClient({ clientId: process.env.CLIENT_ID });
// all credentials with a refresh token, in order to get access tokens automatically
const client = new ImgurClient({
clientId: process.env.CLIENT_ID,
clientSecret: process.env.CLIENT_SECRET,
refreshToken: process.env.REFRESH_TOKEN,
});If you don't have any credentials, you'll need to:
// upload multiple images via fs.createReadStream (node)
const response = await client.upload({
image: createReadStream('/home/kai/dank-meme.jpg'),
type: 'stream',
});
console.log(response.data);If you want to provide metadata, such as a title, description, etc., then pass an object instead of a string:
// upload image via url
const response = await client.upload({
image: 'https://i.imgur.com/someImageHash',
title: 'Meme',
description: 'Dank Meme',
});
console.log(response.data);Acceptable key/values match what the Imgur API expects:
| Key | Description |
|---|---|
image |
A string, stream, or buffer that is a URL pointing to a remote image or video (up to 10MB) |
album |
The id of the album you want to add the media to. For anonymous albums, album should be the deletehash that is returned at creation |
type |
The type of the media that's being transmitted; stream, base64 or url |
name |
The name of the media. This is automatically detected, but you can override |
title |
The title of the media |
description |
The description of the media |
disable_audio |
1 will remove the audio track from a video file |
Instances of ImgurClient emit uploadProgress events so that you can track progress with event listeners.
const client = new ImgurClient({ accessToken: process.env.ACCESS_TOKEN });
client.on('uploadProgress', (progress) => console.log(progress));
await client.upload('/home/kai/cat.mp4');The progress object looks like the following:
{
percent: 1,
transferred: 577,
total: 577,
id: '/home/user/trailer.mp4'
}| Key | Description |
|---|---|
percent |
0 to 1, measures the percentage of upload (e.g., 0, 0.5, 0.8, 1). Basically transferred / total |
transferred |
total number of bytes transferred thus far |
total |
total number of bytes to be transferred |
id |
unique id for the media being transferred; useful when uploading multiple things concurrently |
Requires an image hash or delete hash, which are obtained in an image upload response
client.deleteImage('someImageHash');Update the title and/or description of an image
client.updateImage({
imageHash: 'someImageHash',
title: 'A new title',
description: 'A new description',
});Update multiple images at once:
client.updateImage({
imageHash: 'someImageHash',
title: 'A new title',
description: 'A new description',
});Favorite an image:
client.favoriteImage('someImageHash');client.getGallery({
section: 'hot',
sort: 'viral',
mature: false,
});getGallery() accepts an object of type GalleryOptions. The follow options are available:
| Key | Required | Description |
|---|---|---|
section |
required | hot | top | user |
sort |
optional | viral | top | time | rising (only available with user section). Defaults to viral |
page |
optional | number - the data paging number |
window |
optional | Change the date range of the request if the section is top. Accepted values are day | week | month | year | all. Defaults to day |
showViral |
optional | true | false - Show or hide viral images from the user section. Defaults to true |
mature |
optional | true | false - Show or hide mature (nsfw) images in the response section. Defaults to false. NOTE: This parameter is only required if un-authed. The response for authed users will respect their account setting |
album_previews |
optional | true | false - Include image metadata for gallery posts which are albums |
client.getSubredditGallery({
subreddit: 'wallstreetbets',
sort: 'time',
});getSubredditGallery() accepts an object of type SubredditGalleryOptions. The follow options are available:
| Key | Required | Description |
|---|---|---|
subreddit |
required | A valid subreddit name |
sort |
optional | time | top - defaults to time |
page |
optional | number - the data paging number |
window |
optional | Change the date range of the request if the section is top. Accepted values are day | week | month | year | all. Defaults to week |
client.searchGallery({
query: 'title: memes',
});searchGallery() accepts an object of type SearchGalleryOptions. The follow options are available:
| Key | Required | Description |
| -------------- | -------- | --------------------------------------------------------------------- | ------ | ------- | ------ | ------------------------- |
| query or q | required | Query string |
| sort | optional | time | viral | top - defaults to time |
| page | optional | number - the data paging number |
| window | optional | Change the date range of the request if the sort is top -- to day | week | month | year | all, defaults to all. |
Additionally, the following advanced search query options can be set (NOTE: if any of the below are set in the options, the query option is ignored and these will take precedent):
| Key | Required | Description |
|---|---|---|
q_all |
optional | Search for all of these words (and) |
q_any |
optional | Search for any of these words (or) |
q_exactly |
optional | Search for exactly this word or phrase |
q_not |
optional | Exclude results matching this string |
q_type |
optional | Show results for any file type, jpg | png | gif | anigif (animated gif) | album |
q_size_px |
optional | Size ranges, small (500 pixels square or less) | med (500 to 2,000 pixels square) | big (2,000 to 5,000 pixels square) | lrg (5,000 to 10,000 pixels square) | huge (10,000 square pixels and above) |
const album = await client.getAlbum('XtMnA');