API guide

Automate Transcription Examples You Can Run

Four complete programs and three no-code recipes. Each one is a real file: copy it or download it, put in your key and run it. They have no dependencies to install, so they are easy to read and easy to change.

You need an API key. A free account is enough to try them.

What people automate

Sales and support calls

When your phone system finishes a call, send its recording link. The transcript lands in the CRM record or the ticket, so nobody has to listen again to find what was agreed.

A shared folder of recordings

Meetings, interviews and lectures dropped into one folder come back as text and subtitle files next to the originals, without anyone opening a website.

Every new podcast episode

The moment an episode is in the feed, it is transcribed. Use the text for show notes, a blog post, search on your site and an accessible transcript page.

Voicemail and voice notes as messages

A voicemail or a voice memo arrives in Slack, Teams or e-mail as text a minute or two later, readable in a meeting and searchable afterwards.

Subtitles in a video pipeline

A video is exported, the timed segments come back, and your pipeline writes the SRT file and attaches it before publishing.

Research and interview archives

Hundreds of interviews are sent in one batch overnight and come back with speakers marked, ready for coding and quoting with exact times.

Transcribe a folder into TXT and SRT

Node.js 18+, no dependencies

Point it at a folder. Every audio or video file that has no transcript next to it is uploaded, and when the transcript is ready the script writes a .txt file (with speakers, when they were recognised) and an .srt subtitle file beside the original. Files that already have a .txt are skipped, so it can run every night from cron or Task Scheduler and only pick up what is new.

It also shows the two things a real integration needs: sending a large file in ordered chunks, and reading a long transcript page by page.

Run it
TRANSCRIFY_KEY=trk_... node transcribe-folder.mjs ./recordings
transcribe-folder.mjs
#!/usr/bin/env node
// Transcribe every recording in a folder.
//
// For each audio or video file that has no .txt next to it yet, this uploads
// the file, waits for the transcript and writes two files beside it:
//   interview.mp3  ->  interview.txt  (text, with speakers when recognised)
//                      interview.srt  (subtitles with timestamps)
// Run it again whenever new recordings appear (or from cron): finished files
// are skipped.
//
//   export TRANSCRIFY_KEY=trk_...
//   node transcribe-folder.mjs ./recordings
//
// Node 18 or newer, no dependencies. Scopes: files.write, files.read.

import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises'
import { existsSync } from 'node:fs'
import { randomUUID } from 'node:crypto'
import path from 'node:path'

const API = process.env.TRANSCRIFY_API ?? 'https://api.transcrify.com'
const KEY = process.env.TRANSCRIFY_KEY
const FOLDER = process.argv[2]

const MEDIA = /\.(mp3|m4a|wav|ogg|opus|flac|aac|wma|amr|mp4|mov|mkv|webm|avi|m4v)$/i
const SINGLE_REQUEST_MAX = 45 * 1024 * 1024 // requests are limited to 50 MB
const CHUNK_SIZE = 20 * 1024 * 1024
const FAILED = ['transcription_failed', 'download_failed', 'youtube_download_failed', 'audio_extraction_failed', 'upload_failed']

if (!KEY || !FOLDER) {
  console.error('Usage: TRANSCRIFY_KEY=trk_... node transcribe-folder.mjs <folder>')
  process.exit(2)
}

const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))

/** One API call. Waits and repeats on 429; throws with the API's error code otherwise. */
async function api(method, route, body) {
  for (;;) {
    const response = await fetch(API + route, {
      method,
      headers: { 'X-Api-Key': KEY, ...(body && !(body instanceof FormData) ? { 'Content-Type': 'application/json' } : {}) },
      body: body instanceof FormData ? body : body ? JSON.stringify(body) : undefined
    })
    if (response.status === 429) {
      await sleep((Number(response.headers.get('Retry-After')) || 5) * 1000)
      continue
    }
    const data = await response.json().catch(() => ({}))
    if (!response.ok) {
      const error = new Error(data?.error?.message ?? `HTTP ${response.status}`)
      error.code = data?.error?.code
      error.status = response.status
      throw error
    }
    return data
  }
}

/** Uploads a file in one request, or in ordered chunks when it is large. Returns the file id. */
async function upload(filePath) {
  const name = path.basename(filePath)
  const { size } = await stat(filePath)

  if (size <= SINGLE_REQUEST_MAX) {
    const form = new FormData()
    form.append('file', new Blob([await readFile(filePath)]), name)
    return (await api('POST', '/api/v1/files', form)).id
  }

  const totalChunks = Math.ceil(size / CHUNK_SIZE)
  const uid = randomUUID()
  const handle = await open(filePath, 'r')
  let id
  try {
    for (let chunk = 1; chunk <= totalChunks; chunk++) {
      const buffer = Buffer.alloc(Math.min(CHUNK_SIZE, size - (chunk - 1) * CHUNK_SIZE))
      await handle.read(buffer, 0, buffer.length, (chunk - 1) * CHUNK_SIZE)

      const form = new FormData()
      form.append('file', new Blob([buffer]), name)
      form.append('uid', uid)
      if (chunk === 1) {
        form.append('totalChunks', String(totalChunks))
        id = (await api('POST', '/api/v1/files', form)).id
      } else {
        form.append('currentChunk', String(chunk))
        await api('POST', '/api/v1/files/chunk', form)
      }
      process.stdout.write(`\r  uploading ${Math.round((chunk / totalChunks) * 100)}%`)
    }
    process.stdout.write('\n')
  } finally {
    await handle.close()
  }
  return id
}

async function waitUntilTranscribed(id) {
  for (;;) {
    const file = await api('GET', `/api/v1/files/${id}`)
    if (file.statusLabel === 'transcribed') return
    if (FAILED.includes(file.statusLabel)) throw new Error(file.statusLabel)
    await sleep(20_000)
  }
}

/** The whole transcript as timed segments; long ones come in pages. */
async function readSegments(id) {
  const segments = []
  for (let offset = 0; offset !== null;) {
    const page = await api('GET', `/api/v1/files/${id}/transcript?offset=${offset}&limit=1000`)
    segments.push(...page.segments)
    offset = page.nextOffset
  }
  return segments
}

const srtTime = (seconds) => {
  const ms = Math.round(seconds * 1000)
  const pad = (n, width = 2) => String(n).padStart(width, '0')
  return `${pad(Math.floor(ms / 3_600_000))}:${pad(Math.floor(ms / 60_000) % 60)}:${pad(Math.floor(ms / 1000) % 60)},${pad(ms % 1000, 3)}`
}

function toText(segments) {
  const lines = []
  let speaker
  for (const segment of segments) {
    if (segment.speaker && segment.speaker !== speaker) {
      speaker = segment.speaker
      lines.push(`\n${speaker}:`)
    }
    lines.push(segment.text.trim())
  }
  return lines.join('\n').trim() + '\n'
}

const toSrt = segments => segments
  .filter(segment => segment.start !== null && segment.end !== null)
  .map((segment, i) => `${i + 1}\n${srtTime(segment.start)} --> ${srtTime(segment.end)}\n${segment.text.trim()}\n`)
  .join('\n')

const withoutExtension = file => file.replace(/\.[^.]+$/, '')

// Recordings that have no transcript next to them yet.
const names = (await readdir(FOLDER))
  .filter(name => MEDIA.test(name) && !existsSync(path.join(FOLDER, `${withoutExtension(name)}.txt`)))
  .sort()
let done = 0
for (const name of names) {
  const filePath = path.join(FOLDER, name)
  const base = withoutExtension(filePath)

  console.log(name)
  try {
    const id = await upload(filePath)
    console.log(`  accepted as file ${id}, transcribing...`)
    await waitUntilTranscribed(id)
    const segments = await readSegments(id)
    await writeFile(`${base}.txt`, toText(segments))
    const srt = toSrt(segments)
    if (srt) await writeFile(`${base}.srt`, srt)
    console.log(`  saved ${path.basename(base)}.txt${srt ? ' and .srt' : ''}`)
    done++
  } catch (error) {
    console.error(`  failed: ${error.message}`)
    // 401: the key is wrong. 402: the account has no allowance left.
    // Nothing later would get through either.
    if (error.status === 401 || error.status === 402) break
  }
}
console.log(`${done} of ${names.length} new recordings transcribed.`)

Post finished transcripts to Slack

Node.js 18+, no dependencies

A small web server that receives the webhook, checks its signature, answers at once and then fetches the transcript and posts the beginning of it to a Slack channel. Failed transcriptions are reported too.

This is the pattern for anything that should happen "when a transcript is ready": swap the Slack call for a CRM note, an e-mail, a database insert or a call to a language model that writes the summary your team wants.

Run it
node webhook-to-slack.mjs
webhook-to-slack.mjs
#!/usr/bin/env node
// Receive Transcrify webhooks and post every finished transcript to Slack.
//
// 1. Run this somewhere reachable over https (a small server, or behind a
//    tunnel while testing) and register its address once:
//
//      curl -X POST https://api.transcrify.com/api/v1/webhooks \
//        -H "X-Api-Key: $TRANSCRIFY_KEY" -H "Content-Type: application/json" \
//        -d '{"url":"https://hooks.example.com/transcrify",
//             "events":["file.transcription.completed","file.transcription.failed"]}'
//
//    The answer contains "secret": "whsec_...". It is shown only once.
//
// 2. Start the receiver:
//
//      export TRANSCRIFY_KEY=trk_...                    (scope files.read)
//      export TRANSCRIFY_WEBHOOK_SECRET=whsec_...
//      export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
//      node webhook-to-slack.mjs
//
// Node 18 or newer, no dependencies.

import { createServer } from 'node:http'
import { createHmac, timingSafeEqual } from 'node:crypto'

const API = process.env.TRANSCRIFY_API ?? 'https://api.transcrify.com'
const { TRANSCRIFY_KEY, TRANSCRIFY_WEBHOOK_SECRET, SLACK_WEBHOOK_URL } = process.env
const PORT = Number(process.env.PORT ?? 8787)

if (!TRANSCRIFY_KEY || !TRANSCRIFY_WEBHOOK_SECRET || !SLACK_WEBHOOK_URL) {
  console.error('Set TRANSCRIFY_KEY, TRANSCRIFY_WEBHOOK_SECRET and SLACK_WEBHOOK_URL.')
  process.exit(2)
}

/** True when the request was signed by Transcrify within the last five minutes. */
function verified(rawBody, header) {
  const parts = Object.fromEntries(String(header ?? '').split(',').map(part => part.split('=')))
  if (!parts.t || !parts.v1) return false
  const expected = createHmac('sha256', TRANSCRIFY_WEBHOOK_SECRET).update(`${parts.t}.${rawBody}`).digest('hex')
  const given = Buffer.from(parts.v1)
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
  return fresh && given.length === expected.length && timingSafeEqual(Buffer.from(expected), given)
}

// Deliveries are at-least-once: remember what was handled so a repeat is harmless.
const handled = new Set()

async function postToSlack(text) {
  const response = await fetch(SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text })
  })
  if (!response.ok) throw new Error(`Slack answered ${response.status}`)
}

async function handle(message) {
  const { event, data } = message
  if (event === 'file.transcription.failed') {
    await postToSlack(`:warning: *${data.fileName}* could not be transcribed.`)
    return
  }
  if (event !== 'file.transcription.completed') return

  // The text is not in the webhook on purpose: fetch it with the key.
  const response = await fetch(`${API}/api/v1/files/${data.fileId}`, { headers: { 'X-Api-Key': TRANSCRIFY_KEY } })
  if (!response.ok) throw new Error(`Transcrify answered ${response.status}`)
  const file = await response.json()

  const minutes = Math.max(1, Math.round((file.duration ?? 0) / 60))
  const text = file.transcriptionText ?? ''
  const excerpt = text.length > 1500 ? `${text.slice(0, 1500)}…` : text
  await postToSlack(`:memo: *${file.fileName}* (${minutes} min) is transcribed.\n>>> ${excerpt}`)
}

createServer((request, response) => {
  if (request.method !== 'POST') {
    response.writeHead(405).end()
    return
  }
  const chunks = []
  request.on('data', chunk => chunks.push(chunk))
  request.on('end', () => {
    // Verify against the raw bytes, before any JSON parsing.
    const rawBody = Buffer.concat(chunks).toString('utf8')
    if (!verified(rawBody, request.headers['x-transcrify-signature'])) {
      response.writeHead(400).end()
      return
    }

    // Answer first (Transcrify waits 10 seconds at most), work afterwards.
    response.writeHead(204).end()

    const delivery = request.headers['x-transcrify-delivery']
    if (handled.has(delivery)) return
    handled.add(delivery)

    handle(JSON.parse(rawBody)).catch(error => console.error(`Delivery ${delivery}: ${error.message}`))
  })
}).listen(PORT, () => console.log(`Listening for Transcrify webhooks on :${PORT}`))

Transcribe every new podcast episode

Python 3.9+, standard library only

Run it on a schedule. It reads the RSS feed, sends each episode it has not seen to Transcrify by the address of its audio file, and on later runs saves the finished transcripts as text files. The audio never passes through the machine that runs the script, which makes it cheap to host: a free scheduled job is enough.

It works because a recording can be sent by URL without saying how long it is. The same idea covers any source that publishes links: a video platform, a learning system, a recordings bucket.

Run it
TRANSCRIFY_KEY=trk_... python3 podcast-feed.py https://example.com/feed.xml
podcast-feed.py
#!/usr/bin/env python3
"""Transcribe every new episode of a podcast from its RSS feed.

Run it on a schedule (cron, a GitHub Action, a serverless timer). Each run:
  1. sends episodes it has not seen yet to Transcrify by their audio URL,
     so the audio never passes through this machine;
  2. saves the transcript of every episode that has finished since last time
     as transcripts/<episode title>.txt.

    export TRANSCRIFY_KEY=trk_...
    python3 podcast-feed.py https://example.com/feed.xml

Python 3.9 or newer, standard library only. Scopes: files.write, files.read.
Progress is kept in podcast-state.json next to the script.
"""
import json
import os
import re
import sys
import urllib.error
import urllib.request
import xml.etree.ElementTree as ET
from pathlib import Path

API = os.environ.get("TRANSCRIFY_API", "https://api.transcrify.com")
KEY = os.environ.get("TRANSCRIFY_KEY")
STATE_FILE = Path(__file__).with_name("podcast-state.json")
OUT_DIR = Path("transcripts")
FAILED = {"transcription_failed", "download_failed", "audio_extraction_failed", "upload_failed"}
# Newest episodes first; raise this to work through a back catalogue.
MAX_NEW_PER_RUN = 5


def api(method, route, body=None):
    request = urllib.request.Request(
        API + route,
        method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"X-Api-Key": KEY, "Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(request, timeout=60) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        detail = json.loads(error.read() or b"{}").get("error", {})
        raise RuntimeError(f"{error.code} {detail.get('code', '')}: {detail.get('message', '')}") from None


def episodes(feed_url):
    """(guid, title, audio url) for every item in the feed that has an enclosure."""
    request = urllib.request.Request(feed_url, headers={"User-Agent": "podcast-transcripts/1.0"})
    with urllib.request.urlopen(request, timeout=60) as response:
        root = ET.parse(response).getroot()
    for item in root.iter("item"):
        enclosure = item.find("enclosure")
        if enclosure is None or not enclosure.get("url"):
            continue
        title = (item.findtext("title") or "Episode").strip()
        yield (item.findtext("guid") or enclosure.get("url")).strip(), title, enclosure.get("url")


def safe_name(title):
    return re.sub(r"[^\w\- ]+", "", title).strip()[:120] or "episode"


def main():
    if not KEY or len(sys.argv) != 2:
        sys.exit("Usage: TRANSCRIFY_KEY=trk_... python3 podcast-feed.py <feed url>")

    state = json.loads(STATE_FILE.read_text()) if STATE_FILE.exists() else {}

    # 1. Send new episodes. No length is needed: Transcrify measures it.
    sent = 0
    for guid, title, url in episodes(sys.argv[1]):
        if guid in state or sent >= MAX_NEW_PER_RUN:
            continue
        try:
            file = api("POST", "/api/v1/files/url", {"url": url, "fileName": title})
        except RuntimeError as error:
            print(f"Not accepted: {title} ({error})")
            if str(error).startswith("402"):
                break  # no allowance left; try again after topping up
            continue
        state[guid] = {"id": file["id"], "title": title, "status": "sent"}
        sent += 1
        print(f"Sent: {title}")

    # 2. Collect what has finished.
    OUT_DIR.mkdir(exist_ok=True)
    for entry in state.values():
        if entry["status"] != "sent":
            continue
        file = api("GET", f"/api/v1/files/{entry['id']}")
        if file["statusLabel"] == "transcribed":
            (OUT_DIR / f"{safe_name(entry['title'])}.txt").write_text(file.get("transcriptionText") or "", encoding="utf-8")
            entry["status"] = "done"
            print(f"Saved: {entry['title']}")
        elif file["statusLabel"] in FAILED:
            entry["status"] = "failed"
            print(f"Failed ({file['statusLabel']}): {entry['title']}")

    STATE_FILE.write_text(json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8")


if __name__ == "__main__":
    main()

One recording from the command line

bash, curl and jq

The shortest complete integration: send a link, wait, print the text. Useful on its own in a terminal and as the starting point for a step in a CI job or a shell pipeline.

Run it
TRANSCRIFY_KEY=trk_... ./transcribe-url.sh https://example.com/call.mp3
transcribe-url.sh
#!/usr/bin/env bash
# Transcribe a recording that is reachable by URL and print the text.
#
#   export TRANSCRIFY_KEY=trk_...
#   ./transcribe-url.sh https://example.com/calls/2026-11-20.mp3
#
# Needs curl and jq. The key needs the scopes files.write and files.read.
set -euo pipefail

API="https://api.transcrify.com"
URL="$1"

# 1. Hand over the URL. Transcrify downloads the file itself.
id=$(jq -n --arg url "$URL" '{url: $url}' \
  | curl -fsS -X POST "$API/api/v1/files/url" \
      -H "X-Api-Key: $TRANSCRIFY_KEY" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq -r .id)
echo "Accepted as file $id" >&2

# 2. Wait. A webhook is the better way in production; polling is fine for a script.
while true; do
  file=$(curl -fsS "$API/api/v1/files/$id" -H "X-Api-Key: $TRANSCRIFY_KEY")
  status=$(jq -r .statusLabel <<<"$file")
  case "$status" in
    transcribed)
      # 3. Print the text.
      jq -r .transcriptionText <<<"$file"
      exit 0
      ;;
    *failed)
      echo "Could not be transcribed: $status" >&2
      exit 1
      ;;
  esac
  echo "  $status..." >&2
  sleep 20
done

Without code: Zapier, Make and n8n

These tools can already talk to any HTTP API, and that is all it takes. The pattern is always the same two halves: one automation sends the recording's link, another one starts from our webhook and collects the text. The link must open without signing in; most storage and telephony apps can produce such a link.

Zapier

  1. Trigger: whatever produces the recording, for example "New File in Folder" in Dropbox, or a new call in your telephony app.
  2. Action "Webhooks by Zapier", POST to https://api.transcrify.com/api/v1/files/url. Payload type json, data: url = the file link from the trigger. Header: X-Api-Key = your key.
  3. A second Zap with the trigger "Webhooks by Zapier: Catch Hook". Register the address Zapier gives you as a Transcrify webhook (one curl command, on the developers page).
  4. In that Zap: "Webhooks by Zapier" GET https://api.transcrify.com/api/v1/files/ followed by the fileId field from the hook, with the same header. Then send transcriptionText wherever it belongs: a Google Doc, a CRM note, an e-mail.

Make

  1. Scenario 1: a trigger module for your source, then the "HTTP: Make a request" module. Method POST, URL https://api.transcrify.com/api/v1/files/url, header X-Api-Key, body type Raw / JSON: {"url": "…link from the trigger…"}.
  2. Scenario 2: start with "Webhooks: Custom webhook" and register its address as a Transcrify webhook.
  3. Add "HTTP: Make a request" with GET https://api.transcrify.com/api/v1/files/ followed by data.fileId from the webhook, and "Parse response" switched on.
  4. Use transcriptionText from that module in the next one: Notion, Airtable, Slack, Google Docs.

n8n

  1. Workflow 1: your trigger node, then an "HTTP Request" node. POST https://api.transcrify.com/api/v1/files/url, Send Headers: X-Api-Key, Send Body as JSON with url. If the file is only available as binary data in n8n, POST it to /api/v1/files instead with Body Content Type "Form-Data" and a binary field named file.
  2. Workflow 2: a "Webhook" node (POST). Register its production URL as a Transcrify webhook.
  3. An "HTTP Request" node: GET https://api.transcrify.com/api/v1/files/{{ $json.body.data.fileId }} with the X-Api-Key header.
  4. Continue with any node: write a file, create a page, send a message. For subtitles, call /api/v1/files/{id}/transcript and build the SRT in a Code node.

The names of modules and fields are the ones these tools use at the time of writing; if one has moved, look for its generic HTTP request and incoming webhook building blocks.

Start with one recording

Create a key, run the one-line script on a file you already have, then grow it into the automation you need.