Core concept

Async Transcription Jobs: Submit, Poll, and Receive Results

Every transcription in Wisprs is an async job. Submit a URL or file, receive a jobId immediately, then poll for status or configure a webhook to be notified on completion.

Submit a URL

Send a YouTube link, TikTok URL, podcast feed, or any direct audio/video URL:

import { WisprsClient } from '@wisprs/sdk';

const client = new WisprsClient({ apiKey: process.env.WISPRS_API_KEY! });

const job = await client.transcriptions.create({
  source: { url: 'https://youtube.com/watch?v=dQw4w9WgXcQ' },
  language: 'en',
});

console.log(job.id); // → 42

json

{
  "success": true,
  "data": {
    "jobId": 42,
    "status": "queued"
  }
}

Dashboard Inbox — submit a URL or upload a file — Dashboard Inbox — paste a YouTube link, upload a file, import a playlist, or connect a podcast feed

Job status lifecycle

Poll GET /api/v1/jobs/{id} to check progress:

const result = await client.jobs.wait(job.id); // polls every 2s, 2m timeout
console.log(result.transcriptText);

json

{
  "success": true,
  "data": {
    "id": 42,
    "status": "completed",
    "transcriptionId": 99,
    "processingTimeMs": 14200,
    "createdAt": "2026-06-17T10:00:00.000Z",
    "completedAt": "2026-06-17T10:00:14.000Z"
  }
}

Status values

queued — waiting for a processing slot
downloading — extracting audio from the source URL
processing — transcribing your audio
completed — transcript is ready, transcriptionId is set
failed — see errorMessage; retry with POST /api/v1/jobs/{id}/retry

Retrieve the transcript

const transcription = await client.transcriptions.get(99);
console.log(transcription.transcriptText);

json

{
  "success": true,
  "data": {
    "id": 99,
    "status": "completed",
    "transcriptText": "Never gonna give you up...",
    "language": "en",
    "duration": 212,
    "speakerCount": 1,
    "createdAt": "2026-06-17T10:00:14.000Z"
  }
}

Transcription detail — file info, waveform, export panel, and transcript tabs — Completed transcription — duration, language, status, and one-click downloads

Quality setting

Use options.sttQuality to trade off speed vs accuracy:

fast — lowest latency, suitable for short clips and drafts
balanced — default. Good accuracy for most content
accurate — highest accuracy, slower. Recommended for dense technical or multilingual content

const job = await client.transcriptions.create({
  source: { url: 'https://youtube.com/watch?v=dQw4w9WgXcQ' },
  language: 'en',
  options: { sttQuality: 'accurate' },
});

Speaker diarization

Speaker diarization — identifying who said what — is automatically enabled on Pro plans and above. No configuration needed: when diarization is available for your plan, the transcript will include speaker labels in the json and md export formats.

Retry a failed job

// Resets status to "queued" and re-enqueues
await client.jobs.retry(42);

Tip: For high volume, set up a webhook endpoint instead of polling. See the Webhooks guide.

FAQ

How long do transcription jobs take?

Most jobs complete in a fraction of the audio duration. Short clips (under 5 minutes) typically complete in under a minute. Processing time may be higher during peak load.

What happens if a job fails?

The job status moves to failed and an errorMessage is set. Common causes include inaccessible URLs, unsupported formats, or content that violates usage policies. Use the retry endpoint to re-queue the job.

Can I cancel a job?

Jobs in the queued state can be cancelled. Jobs already in downloading or processing will complete before cancellation takes effect.