API Documentation

Transcribe social media videos programmatically with a single API call.

Base URL

https://soscripted.com/api/public

Authentication

All API requests require a Bearer token in the Authorization header. You can generate an API key from your API Keys dashboard.

Header

Authorization: Bearer sk_your_api_key_here

POST /transcribe

Submit a video URL for transcription. The API will process the video and return the transcript. Each request costs 1 credit.

Request Body

Field	Type	Description
url	string	Video URL from a supported platform (YouTube, TikTok, Instagram, Facebook, Twitter/X, LinkedIn, Pinterest)

Example Request

POST /api/public/transcribe HTTP/1.1
Host: soscripted.com
Authorization: Bearer sk_your_api_key_here
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response (JSON)

By default, the API blocks until transcription completes and returns a JSON response.

Success Response (200)

{
  "ok": true,
  "caption": {
    "text": "Full transcript text here...",
    "segments": [
      { "start": 0.0, "end": 2.5, "text": "Hello world" },
      { "start": 2.5, "end": 5.0, "text": "This is a transcript" }
    ]
  }
}

Error Response (4xx/5xx)

{
  "error": "Error description"
}

Response (SSE Streaming)

To receive real-time progress updates, include Accept: text/event-stream in your request headers.

SSE Events

event: progress
data: {"stage":"downloading","pct":10}

event: progress
data: {"stage":"transcribing","pct":50}

event: final
data: {"ok":true,"caption":{"text":"...","segments":[...]}}

event: done
data: {"ok":true}

Status Codes

Code	Description
200	Transcription completed successfully
400	Bad request (missing URL or unsupported platform)
401	Unauthorized (missing or invalid API key)
402	Insufficient credits
500	Transcription failed
504	Timeout (transcription took too long)

Code Examples

JavaScript (JSON response)

fetch

const response = await fetch("https://soscripted.com/api/public/transcribe", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  }),
});

const data = await response.json();

if (data.ok) {
  console.log("Transcript:", data.caption.text);
} else {
  console.error("Error:", data.error);
}

JavaScript (SSE streaming)

EventSource via fetch

const response = await fetch("https://soscripted.com/api/public/transcribe", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key_here",
    "Content-Type": "application/json",
    "Accept": "text/event-stream",
  },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop() || "";

  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      console.log("Event:", data);
    }
  }
}

Python (JSON response)

requests

import requests

response = requests.post(
    "https://soscripted.com/api/public/transcribe",
    headers={
        "Authorization": "Bearer sk_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
    timeout=600,
)

data = response.json()

if data.get("ok"):
    print("Transcript:", data["caption"]["text"])
else:
    print("Error:", data.get("error"))

Python (SSE streaming)

requests + sseclient

import requests
import json

response = requests.post(
    "https://soscripted.com/api/public/transcribe",
    headers={
        "Authorization": "Bearer sk_your_api_key_here",
        "Content-Type": "application/json",
        "Accept": "text/event-stream",
    },
    json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
    stream=True,
)

for line in response.iter_lines(decode_unicode=True):
    if line.startswith("data: "):
        data = json.loads(line[6:])
        print("Event:", data)
        if "caption" in data:
            print("Transcript:", data["caption"]["text"])

Supported Platforms

YouTube

TikTok

Instagram

Facebook

Twitter / X