Neatly Positioned Magazines

    imgur
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.3 • Public • Published

    imgur

    Unofficial JavaScript library for the Imgur.com API

    npm version Build states

    Join the community on GitHub Discussions

    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',
      },
      {
        image: createReadStream('/home/kai/another-dank-meme'),
        type: 'stream',
      },
    ]);
    response.data.forEach((r) => console.log(r.link));

    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

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

    Delete an image

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

    client.delete('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',
      },
      {
        imageHash: 'anotherImageHash',
        title: 'A better title',
        description: 'A better 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:

    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

    Get subreddit gallery images

    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

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

    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)

    Get album info

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

    Dependencies (2)

    Dev Dependencies (27)

    Install

    npm i imgur

    DownloadsWeekly Downloads

    2,563

    Version

    2.1.3

    License

    MIT

    Unpacked Size

    79.9 kB

    Total Files

    28

    Last publish

    Collaborators

    • kai
    • keneucker