ReelScribe Node.js SDK

Official Node.js/TypeScript client for the ReelScribe API — transcribe Instagram Reels, TikTok videos, and YouTube Shorts programmatically.

Installation

npm install reelscribe

Quick Start

import { ReelScribe } from 'reelscribe'

const rs = new ReelScribe('rs_your_api_key')

// Submit a video for transcription
const { requestId } = await rs.transcribe({
  url: 'https://www.instagram.com/reel/ABC123/',
})

// Poll for the result
const transcription = await rs.getTranscription({ requestId })
console.log(transcription.transcription)

Get your API key from the ReelScribe dashboard.

Usage

Transcribe a Video

Submit an Instagram Reel, TikTok video, or YouTube Short for transcription. Costs 1 credit per request.

const result = await rs.transcribe({
  url: 'https://www.youtube.com/shorts/dQw4w9WgXcQ',
})

console.log(result.requestId) // use this to check status

With Webhook

Instead of polling, provide a resumeUrl to receive a POST when the transcription is ready:

const result = await rs.transcribe({
  url: 'https://www.tiktok.com/@user/video/1234567890',
  resumeUrl: 'https://your-server.com/webhook',
})

Your server will receive the full transcription result as a POST request. See the webhook docs for the payload format.

Get a Transcription

Retrieve a transcription by the requestId returned from transcribe():

const t = await rs.getTranscription({ requestId: '550e8400-...' })

console.log(t.status)         // 'completed'
console.log(t.transcription)  // 'The full transcription text...'
console.log(t.caption)        // Original post caption
console.log(t.hashtags)       // ['tag1', 'tag2']
console.log(t.stats)          // { likes: 1234, views: 56789, comments: 42 }
console.log(t.segments)       // [{ start: 0, end: 2.5, text: 'Hello...' }]

Or fetch by Convex document ID:

const t = await rs.getTranscription({ id: 'abc123' })

List Transcriptions

// All transcriptions
const { transcriptions, total } = await rs.listTranscriptions()

// Filter by status
const completed = await rs.listTranscriptions({ status: 'completed' })

Check Credits

const credits = await rs.getCredits()

console.log(credits.credits)            // 450
console.log(credits.tier)               // 'creator'
console.log(credits.subscriptionStatus) // 'active'
console.log(credits.storageUsed)        // 42
console.log(credits.storageLimit)       // 100

Settings

// Read settings
const settings = await rs.getSettings()
console.log(settings.autoPruneStorage) // true

// Update settings
await rs.updateSettings({ autoPruneStorage: false })

Health Check

const health = await rs.health()
console.log(health.healthy) // true

Error Handling

All API errors throw a ReelScribeError with a machine-readable code and HTTP status:

import { ReelScribe, ReelScribeError } from 'reelscribe'

try {
  await rs.transcribe({ url: 'https://www.instagram.com/reel/ABC123/' })
} catch (err) {
  if (err instanceof ReelScribeError) {
    console.log(err.code)    // 'INSUFFICIENT_CREDITS'
    console.log(err.status)  // 402
    console.log(err.message) // 'You need at least 1 credit'
  }
}

| Code | Status | Description | |------|--------|-------------| | INVALID_REQUEST | 400 | Bad request body or missing fields | | INVALID_URL | 400 | Unsupported video platform | | UNAUTHORIZED | 401 | Missing or invalid API key | | INSUFFICIENT_CREDITS | 402 | No credits remaining | | STORAGE_LIMIT | 403 | Transcript storage full | | NOT_FOUND | 404 | Transcription not found | | SERVICE_ERROR | 503 | Transcription service unavailable (credit refunded) |

Configuration

const rs = new ReelScribe('rs_your_api_key', {
  // Override the base URL (useful for testing)
  baseUrl: 'https://staging.reelscribe.app',
  // Provide a custom fetch implementation
  fetch: myCustomFetch,
})

Supported Platforms

| Platform | Example URL | |----------|-------------| | Instagram Reels | https://www.instagram.com/reel/ABC123/ | | TikTok Videos | https://www.tiktok.com/@user/video/1234567890 | | YouTube Shorts | https://www.youtube.com/shorts/dQw4w9WgXcQ | | YouTube Videos | https://www.youtube.com/watch?v=dQw4w9WgXcQ |

Requirements

• Node.js 18+ (uses native fetch)
• A ReelScribe account with API access

Links

• ReelScribe — Video transcription for content creators
• API Documentation — Full endpoint reference & API key management
• Pricing — Plans starting at $9.99/month

License

MIT

Built by SIÁN Agency