The VIDY logotype

VIDY API for Node.js

Search, discover, watch, and share talking videos from VIDY using the VIDY API.

⚠️ This project has been archived

No future updates are planned. Feel free to continue using it, but expect no support.

  • Built to ease VIDY integration and testing.
  • Uses the VIDY API.
  • The sandbox API makes it easy to get started:
    • Open access, no special authorization required.
    • Preconfigured in the CLI tool.
    • Preconfigured in the code examples.
    • Uses a smaller dataset of VIDYs.
    • Rate limited to maximum 1 request per second.
  • Requires Node.js v6.0.0 or newer.

Command line usage

For easy developer testing, use the vidy command line interface (CLI).

Outputs JSON results from the VIDY API. See the VIDY API documentation for details regarding the return value format.

CLI arguments, such as API access key id and key secret, can be pre-configured using a ~/.vidyrc file containing the respective command line options as JSON key/value pairs.

# NOTE: install vidy for system-wide usage.
npm install --global vidy

# NOTE: show the CLI help.
vidy --help

# NOTE: a simple VIDY API query.
vidy query "hello world"

# NOTE: a simple VIDY API query.
vidy search '{"q":"hello space","limits":[1],"types":["clips"],"files":["landscapeVideo240"]}'

# Pass the output to for example `jq` for processing.
vidy query --limit 3 "hello everybody" | jq

Library usage

# NOTE: in your nodejs project folder.
npm install --save vidy

See the ./example/ directory for both example vidy.query(...) and

See the VIDY API documentation for details regarding the return value format.

const {
  create: createVidy,
} = require("vidy");

const vidyConfig = {
  application: {
    locale: "en-US",
  authentication: {
    keyId: "sandbox",
    keySecret: "sandbox",
  urls: {
    api: "",
    clip: "",
    search: "",

const vidy = createVidy(vidyConfig);

vidy.query("hello world", 1).then((vidySearchResult) => {
      const firstVideoText = vidySearchResult.clips.results[0].text;
      const firstVideoUrl = vidySearchResult.clips.results[0].files.landscapeVideo240.url;

      console.log(JSON.stringify(firstVideoText), firstVideoUrl);


Patches welcome! Please follow git-flow when submitting pull requests.

Screenshot of the /vidy command used in Slack node-vidy Copyright © 2018 Joel Purra. Released under GNU Affero General Public License version 3.0 (AGPL-3.0). Your donations are appreciated!