Pinterest-dl

Pinterest Downloader

A lightweight, zero-dependency Node.js client for the CEDDSDEV Pinterest Downloader API. Resolve Pinterest pins, videos, and images from regular Pinterest URLs or short pin.it links.

Requirements

• Node.js 18 or newer

Install

npm install pinterest-downloader

Node.js usage

const pinterestDownloader = require('pinterest-downloader');

async function main() {
  const pin = await pinterestDownloader('https://pin.it/2MJmXlPzy');

  console.log('Title:', pin.title);
  console.log('Thumbnail:', pin.thumbnail);

  for (const download of pin.downloads ?? []) {
    console.log(`${download.type} (${download.quality ?? 'original'}):`);
    console.log(download.url);
  }
}

main().catch(console.error);

The returned value is the API's data object:

{
  source_url: 'https://pin.it/2MJmXlPzy',
  pin_id: '1063060687057329710',
  title: 'Pinterest Video Downloader- KlickPin',
  thumbnail: 'https://...',
  downloads: [
    {
      type: 'video',
      quality: 'hd',
      url: 'https://...',
      thumbnail: 'https://...'
    }
  ]
}

Options

const controller = new AbortController();

const pin = await pinterestDownloader(url, {
  timeout: 15_000,
  signal: controller.signal
});

Option	Type	Default	Description
timeout	number	30000	Maximum request time in milliseconds.
signal	AbortSignal	—	Abort the request from the caller.
endpoint	string	CEDDSDEV API	Override the endpoint for a compatible API deployment.

Error handling

Errors are instances of PinterestDownloaderError and include a stable code, with optional status and details fields:

try {
  const pin = await pinterestDownloader(url);
} catch (error) {
  console.error(error.code, error.message);
}

Possible error codes include:

• INVALID_URL — missing, malformed, or unsupported URL.
• INVALID_TIMEOUT — timeout is not a positive number.
• TIMEOUT — the API did not respond before the timeout.
• ABORTED — the caller cancelled the request.
• HTTP_ERROR — the API returned a non-success HTTP status.
• API_ERROR — the API could not process the Pinterest URL.
• INVALID_RESPONSE — the API returned invalid JSON.
• NETWORK_ERROR — the API could not be reached.

CLI

Print a formatted JSON response directly from the terminal:

npx pinterest-downloader "https://pin.it/2MJmXlPzy"

Or install it globally:

npm install --global pinterest-downloader
pinterest-downloader "https://pin.it/2MJmXlPzy"

API endpoint

This package calls the CEDDSDEV endpoint:

GET https://cedds-api.duckdns.org/downloader/pintedl?url=<encoded-pinterest-url>

The library returns the endpoint's data property and throws an error when the response is unsuccessful.

Responsible use

Use this package only for content you have permission to download. Follow Pinterest's terms of service, copyright laws, and the rights of content owners. The package does not bypass private pins, authentication, or access controls.

License

MIT © CEDDSDEV