API Reference

Overview

The v1 API exposes two transcript surfaces: a WebSocket at /api/v1/live for currently-live YouTube videos, and a REST endpoint at /api/v1/transcript for videos that are no longer live. A usage endpoint reports remaining live minutes.

All responses are JSON. WebSocket messages are JSON-encoded text frames. Timestamps use ISO 8601; segment offsets use milliseconds.

Quickstart

Connect to the live WebSocket, send a subscribe message, and read transcript events.

// Node.js example using ws
import WebSocket from "ws";

const ws = new WebSocket("wss://livescript.live/api/v1/live", {
  headers: { Authorization: `Bearer ${process.env.LIVESCRIPT_API_KEY}` },
});

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "subscribe",
    source: "youtube",
    source_id: "abc123DEF45",
    language: "en",
    delivery: "streaming",
  }));
});

ws.on("message", (data) => {
  const event = JSON.parse(data.toString());
  if (event.type === "transcript" && event.status === "final") {
    console.log(event.text);
  }
});

Endpoints

Live WebSocket

Open a WebSocket to wss://livescript.live/api/v1/live and send a single subscribe message. The server streams transcript events until the video ends, you disconnect, or an error closes the socket. One subscribe message is allowed per socket.

{
  "type": "subscribe",
  "source": "youtube",
  "source_id": "abc123DEF45",
  "language": "en",
  "delivery": "streaming"
}

Transcript events

A transcript segment has a stable segment_id. While status is "interim", the text may be revised; each revision increments revision. The final revision has status: "final" and is stable.

{
  "type": "transcript",
  "source": "youtube",
  "source_id": "abc123DEF45",
  "segment_id": "seg_8KQ2m",
  "revision": 2,
  "text": "good bring",
  "start_ms": 124000,
  "end_ms": 125200,
  "status": "interim"
}

{
  "type": "transcript",
  "source": "youtube",
  "source_id": "abc123DEF45",
  "segment_id": "seg_8KQ2m",
  "revision": 3,
  "text": "Good morning.",
  "start_ms": 124000,
  "end_ms": 125700,
  "status": "final"
}

With delivery: "final", the server omits interim revisions and only emits the final segment.

GET /api/v1/transcript

Fetch the transcript of a YouTube video that is no longer live. Returns 404 if the video has no available transcript and 409 if the video is currently live (use the WebSocket instead).

GET https://livescript.live/api/v1/transcript?source=youtube&source_id=abc123DEF45
Authorization: Bearer ls_live_xxx

Response

{
  "source": "youtube",
  "source_id": "abc123DEF45",
  "title": "Stream title",
  "transcript": [
    {
      "segment_id": "cap_1",
      "start_ms": 0,
      "text": "Welcome back to the show.",
      "status": "final"
    },
    {
      "segment_id": "cap_2",
      "start_ms": 4200,
      "text": "Today we're covering the markets.",
      "status": "final"
    }
  ]
}

GET /api/v1/usage

Returns the authenticated account's minute consumption for the current period. Usage is measured in connected live minutes. Non-live transcript fetches do not consume live minutes.

{
  "plan": "pro",
  "period_ends_at": "2026-06-22T00:00:00Z",
  "live_minutes": {
    "included_total": 1500,
    "included_remaining": 420,
    "topup_remaining": 900,
    "total_remaining": 1320
  },
  "limits": {
    "concurrent_live_streams": 1
  }
}

Errors

Errors are returned as a JSON object with a stable code and a human-readable message. On the WebSocket, an error frame is sent immediately before the socket is closed.

{
  "type": "error",
  "code": "SOURCE_NOT_LIVE",
  "message": "The requested YouTube video is not currently live."
}