imgur

Unofficial JavaScript library for the Imgur.com API

Installation

npm install imgur

Usage

Migrating to version 2

Version 2 of the imgur api drops automatic support for filesystem usage. For uploading files from a filesystem, please see the examples using createReadStream.

Import and instantiate with credentials:

// 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:

1. Create an Imgur account
2. Register an application

⚠️ For brevity, the rest of the examples will leave out the import and/or instantiation step.

Upload one or more images and videos

// 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:

Upload and track progress of uploads

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

Delete an image

Requires an image hash or delete hash, which are obtained in an image upload response

client.deleteImage('someImageHash');

Update image information

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

Get gallery images

client.getGallery({
  section: 'hot',
  sort: 'viral',
  mature: false,
});

getGallery() accepts an object of type GalleryOptions. The follow options are available:

Get subreddit gallery images

client.getSubredditGallery({
  subreddit: 'wallstreetbets',
  sort: 'time',
});

getSubredditGallery() accepts an object of type SubredditGalleryOptions. The follow options are available:

Search the gallery

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

Get album info

const album = await client.getAlbum('XtMnA');