Transcripts

Transcripts are the core of the WiseScribe API. Submit any supported URL and receive the full transcript text — synchronously for most platforms, or asynchronously via a background job for others.

Supported platforms

  • Name
    YouTube
    Type
    synchronous
    Description

    All public YouTube videos. Returns instantly via transcript caption data.

  • Name
    Spotify / Apple Podcasts
    Type
    synchronous
    Description

    Public podcast episodes. Transcribed using Whisper-based ASR.

  • Name
    Vimeo
    Type
    synchronous
    Description

    Public Vimeo videos.

  • Name
    TikTok / Instagram / Facebook
    Type
    async
    Description

    Short and long-form videos. Returns a jobId — poll /api/v1/job/:jobId for results.

  • Name
    X (Twitter)
    Type
    async
    Description

    Public posts with video. Returns a jobId — poll for results.

The transcript object

Properties

  • Name
    title
    Type
    string
    Description

    The title of the video or podcast episode as reported by the platform.

  • Name
    url
    Type
    string
    Description

    The canonical URL of the content that was transcribed.

  • Name
    duration
    Type
    string
    Description

    Human-readable duration (e.g., "1:04:32").

  • Name
    durationSeconds
    Type
    integer
    Description

    Duration of the content in seconds.

  • Name
    transcript
    Type
    string
    Description

    The full transcript text in markdown format.

  • Name
    tier
    Type
    string
    Description

    The transcription method used (e.g., "youtube", "whisper", "podcast").

POST/api/v1/transcribe

Create a transcript

Submit a URL for transcription. The response is either synchronous (200) or async (202) depending on the platform.

Required attributes

  • Name
    url
    Type
    string
    Description

    The video or podcast URL to transcribe. Must be https:// and from a supported platform.

Response: synchronous (200)

Returned for YouTube, Vimeo, Spotify, Apple Podcasts, and most podcast URLs. The data object contains the full transcript.

Response: async (202)

Returned for TikTok, Instagram, Facebook, and X. Contains jobId and pollUrl — use these with the job polling endpoint.

Request

POST
/api/v1/transcribe
curl https://wisescribe.ai/api/v1/transcribe \
  -H "Authorization: Bearer wsc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

Synchronous response (200)

{
  "ok": true,
  "data": {
    "title": "Never Gonna Give You Up",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "duration": "3:32",
    "durationSeconds": 212,
    "transcript": "We're no strangers to love\nYou know the rules and so do I...",
    "tier": "youtube"
  }
}

Async response (202)

{
  "ok": true,
  "queued": true,
  "jobId": "a9f3c812-1234-5678-abcd-ef0123456789",
  "pollUrl": "/api/v1/job/a9f3c812-1234-5678-abcd-ef0123456789"
}
GET/api/v1/job/:jobId

Polling async jobs

Poll this endpoint to check the status of a background transcription job. Keep polling until status is "done" or "failed". We recommend 3–5 second intervals — most jobs complete within 30–90 seconds.

Path parameters

  • Name
    jobId
    Type
    string
    Description

    The job ID returned in the 202 response from POST /api/v1/transcribe.

Job statuses

  • Name
    pending
    Type
    string
    Description

    Job is queued and waiting to start. Keep polling.

  • Name
    processing
    Type
    string
    Description

    Transcription is actively in progress. Keep polling.

  • Name
    done
    Type
    string
    Description

    Transcription complete. The data object contains the full result.

  • Name
    failed
    Type
    string
    Description

    Transcription failed — content may be private, removed, or unsupported.

Request

GET
/api/v1/job/:jobId
curl https://wisescribe.ai/api/v1/job/a9f3c812-1234-5678-abcd-ef0123456789 \
  -H "Authorization: Bearer wsc_YOUR_KEY"

Pending / processing (202)

{
  "ok": true,
  "status": "pending"
}

Done (200)

{
  "ok": true,
  "status": "done",
  "data": {
    "id": "3f8a1c2d-4e5f-6789-abcd-ef0123456789",
    "title": "My TikTok Video",
    "url": "https://www.tiktok.com/@user/video/123",
    "duration": "0:58",
    "durationSeconds": 58,
    "transcript": "Hey everyone, today I want to share...",
    "tier": "whisper"
  }
}

Failed (422)

{
  "ok": false,
  "error": "Transcription failed for this job."
}

Was this page helpful?