Skip to main content
A workflow that downloads a video or pulls a transcript often works once and then fails, because sites block the datacenter IPs Pipedream runs on and many videos have no captions. Your workflow can send the link to Importly from a Node.js code step and get the transcript, file or metadata back. No custom app or extra packages are needed.

1. Store your key

Create your key on the API key page (it is shown once). In Pipedream, open Settings > Environment Variables, click New Variable, name it IMPORTLY_API_KEY and paste the key. Leave Secret on, so the value is never shown in the UI. Code steps read it as process.env.IMPORTLY_API_KEY. You can revoke the key on the API key page at any time.

2. Get a transcript in one step

Add a step after your trigger (a schedule, a new row in Google Sheets, an HTTP request): click +, choose Run custom code, and paste:
Node.js code step
To take the link from the trigger, replace the sample link with a value from steps, for example steps.trigger.event.body.url for an HTTP trigger. mode: "auto" uses the video’s captions and falls back to speech-to-text when it has none. wait: true holds the request open for up to 30 seconds, so a caption transcript usually comes back in this step. What the step returns is available to later steps as steps.<step name>.$return_value. If status is still running (long videos transcribed from audio), check it again with GET https://api.importly.io/transcribe/status?id=... using the jobId. A caption transcript costs $0.003; see Pricing & credits.

3. Import a file

POST /import starts a download and returns a jobId right away. The file is ready a few seconds to a few minutes later, so collect it with a second workflow that starts on an HTTP trigger.
  1. Create a new workflow with the HTTP / Webhook trigger and copy its endpoint URL (https://<id>.m.pipedream.net). Deploy it.
  2. In your first workflow, add a code step like the one above that calls POST https://api.importly.io/import with this body:
  3. When the job finishes, Importly sends one POST to the endpoint, and the second workflow runs with the result in steps.trigger.event.body.
In the webhook workflow the result fields sit directly on data: steps.trigger.event.body.data.mediaUrl is the file link and steps.trigger.event.body.data.title the title. A failed job arrives with success set to false and a message (Failed jobs), so check success before the steps that use the file. Deliveries are signed; to reject forged requests, see Verify signatures. mediaUrl is a signed link that expires after 7 days. To keep the file, add a step that uploads it to Google Drive, Dropbox or S3, or have every import land in your own bucket.

Metadata only

For a title, duration and thumbnail without downloading anything, call POST https://api.importly.io/metadata/basic with { "url": "..." } from a code step, then check /metadata/basic/status the same way. See Metadata.

When a step fails

The code above throws on a 4xx or 5xx response, which stops the workflow and shows the error. The JSON body says why, with a code such as INSUFFICIENT_BALANCE or INVALID_URL. Every code is listed in Errors. Using n8n, Make or Zapier instead? See n8n, Make or Zapier.