Subclip Logo

API Reference

Social Media Transcript API

Extract transcripts from supported social media URLs or explicit public downloadable media URLs.

Subclip downloads the media, probes duration, checks credits at 1 credit per source minute, then transcribes and returns text, JSON, or SRT. For current costs, see API credit costs.

OpenAPI-style reference

API endpoints

Download social or public media, transcribe it, and return text, SRT, JSON, or word timestamps.

API v1 storage handling: files uploaded or generated through /api/v1are auto-cleaned and do not count toward the user's storage quota.
POST/api/v1/social-transcripts/uploads

Create public media upload URL

Creates a signed upload URL for public-media transcript jobs.

Bearer auth

Parameters

FieldTypeRequiredDetails
fileNamestringYes
Source media file name
body
contentTypestringNo
Audio or video content type
body
fileSizenumberYes
Declared size in bytes, max 2GB
body

Examples

Request

{
  "fileName": "source.mp4",
  "contentType": "video/mp4",
  "fileSize": 52428800
}

Response

{
  "uploadUrl": "https://...",
  "sourceObjectKey": "user_.../social-transcripts-api/sources/abc123-source.mp4",
  "expiresIn": 900
}

Responses

StatusDescription
200Request succeeded
400Invalid request body or unsupported parameter
401Missing, invalid, or revoked API key
429Rate limit exceeded
500Unexpected processing error
POST/api/v1/social-transcripts/jobs

Start social media transcript

Downloads social or public media, checks credits by duration, transcribes, and returns the requested format.

Bearer auth

Parameters

FieldTypeRequiredDetails
urlstringNo
Instagram, Facebook, YouTube, X, TikTok, or public downloadable URL
body
sourceObjectKeystringNo
Uploaded source media key instead of url
bodyUpload source media
platforminstagram | facebook | youtube | x | tiktok | publicNo
Optional except public downloadable URLs must use public
bodyTranscript options
languagestringYes
Language code for transcription
bodySupported transcript languages
formattext | srt | jsonNo
Output transcript format
bodydefault: textTranscript options
includeWordTimestampsbooleanNo
Include word-by-word timestamp output
bodydefault: falseTranscript options

Examples

Request

{
  "url": "https://www.tiktok.com/@creator/video/...",
  "platform": "tiktok",
  "language": "en",
  "format": "srt",
  "includeWordTimestamps": true
}

Response

{
  "projectId": "stproj_...",
  "status": "queued",
  "runId": "run_...",
  "estimatedCredits": 9,
  "statusUrl": "/api/v1/.../jobs/stproj_...",
  "downloadUrl": "/api/v1/.../jobs/stproj_.../download"
}

Responses

StatusDescription
200Request succeeded
400Invalid request body or unsupported parameter
401Missing, invalid, or revoked API key
429Rate limit exceeded
500Unexpected processing error
GET/api/v1/social-transcripts/jobs/{projectId}

Get social transcript status

Returns transcript output when complete.

Bearer auth

Parameters

FieldTypeRequiredDetails
projectIdstringYes
Social transcript project ID
path

Examples

Response

{
  "projectId": "stproj_...",
  "status": "completed",
  "outputReady": true,
  "format": "srt",
  "output": "1\\n00:00:00,000 --> 00:00:02,000\\nHello world"
}

Responses

StatusDescription
200Request succeeded
400Invalid request body or unsupported parameter
401Missing, invalid, or revoked API key
429Rate limit exceeded
500Unexpected processing error

Upload source media to Subclip

This step is optional. It is useful when you do not want to manage S3 storage infrastructure and want Subclip to handle direct client-side uploads.

1. Create an upload URL

curl -X POST https://www.subclip.app/api/v1/social-transcripts/uploads \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "creator-video.mp4",
    "contentType": "video/mp4",
    "fileSize": 73400320
  }'
{
  "uploadUrl": "https://...",
  "method": "PUT",
  "sourceObjectKey": "user_.../social-transcripts-api/sources/abc123-creator-video.mp4",
  "sourceObjectName": "creator-video.mp4",
  "sourceObjectMimeType": "video/mp4",
  "expiresIn": 900
}

2. Upload the file

curl -X PUT "$SOURCE_UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  -H "Content-Length: 73400320" \
  --data-binary "@creator-video.mp4"

3. Start the job with sourceObjectKey

curl -X POST https://www.subclip.app/api/v1/social-transcripts/jobs \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceObjectKey": "user_.../social-transcripts-api/sources/abc123-creator-video.mp4",
    "sourceObjectName": "creator-video.mp4",
    "sourceObjectMimeType": "video/mp4",
    "language": "en",
    "format": "text"
  }'

Start from a social URL

Subclip infers youtube, instagram, facebook, x, and tiktok from the URL.

curl -X POST https://www.subclip.app/api/v1/social-transcripts/jobs \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@creator/video/...",
    "language": "en"
  }'
{
  "projectId": "stproj_...",
  "status": "queued",
  "runId": "run_...",
  "platform": "tiktok",
  "format": "text",
  "estimatedCredits": null,
  "statusUrl": "/api/v1/social-transcripts/jobs/stproj_..."
}

Start from a public downloadable URL

For a direct media file, public S3 URL, signed S3/R2 URL, or another downloadable HTTP(S) media URL, set platform to public. Without it, the request fails.

curl -X POST https://www.subclip.app/api/v1/social-transcripts/jobs \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-bucket.s3.amazonaws.com/source-video.mp4?X-Amz-Signature=...",
    "platform": "public",
    "language": "en"
  }'

Supported transcript languages

Pass one of these values in language. The field is required so the transcription model can run with the right language hint.

CodeLanguage
afAfrikaans
sqAlbanian
amAmharic
arArabic
hyArmenian
asAssamese
azAzerbaijani
baBashkir
euBasque
beBelarusian
bnBengali
bsBosnian
brBreton
bgBulgarian
caCatalan
zhChinese
hrCroatian
csCzech
daDanish
nlDutch
enEnglish
etEstonian
foFaroese
fiFinnish
frFrench
glGalician
kaGeorgian
deGerman
elGreek
guGujarati
htHaitian Creole
haHausa
hawHawaiian
heHebrew
hiHindi
huHungarian
isIcelandic
idIndonesian
itItalian
jaJapanese
jwJavanese
knKannada
kkKazakh
kmKhmer
koKorean
loLao
laLatin
lvLatvian
lnLingala
ltLithuanian
lbLuxembourgish
mkMacedonian
mgMalagasy
msMalay
mlMalayalam
mtMaltese
miMaori
mrMarathi
mnMongolian
myMyanmar
neNepali
noNorwegian
nnNynorsk
ocOccitan
psPashto
faPersian
plPolish
ptPortuguese
paPunjabi
roRomanian
ruRussian
saSanskrit
srSerbian
snShona
sdSindhi
siSinhala
skSlovak
slSlovenian
soSomali
esSpanish
suSundanese
swSwahili
svSwedish
tlTagalog
tgTajik
taTamil
ttTatar
teTelugu
thThai
boTibetan
trTurkish
tkTurkmen
ukUkrainian
urUrdu
uzUzbek
viVietnamese
cyWelsh
yiYiddish
yoYoruba

Options

FieldRequiredNotes
urlYes, unless sourceObjectKeySocial URL or direct public/signed downloadable media URL
sourceObjectKeyYes, unless urlObject key returned by POST /api/v1/social-transcripts/uploads
sourceObjectNameNoOriginal uploaded source filename
sourceObjectMimeTypeNoUploaded source media MIME type
platformConditionalOptional for supported social URLs, required as public for direct downloadable URLs
languageYesSpoken language code from the supported transcript languages table
formatNotext by default, use text, json, or srt
includeWordTimestampsNoAdds word-level timestamps to the completed status response when available

Poll status

The transcript is ready when outputReady is true.

curl https://www.subclip.app/api/v1/social-transcripts/jobs/stproj_... \
  -H "Authorization: Bearer $SUBCLIP_API_KEY"

Responses

Use format and includeWordTimestamps only when you need structured output or word-level timing.

{
  "format": "json",
  "includeWordTimestamps": true
}
{
  "projectId": "stproj_...",
  "status": "completed",
  "outputReady": true,
  "platform": "youtube",
  "format": "text",
  "durationSeconds": 126,
  "creditsUsed": 3,
  "text": "Full transcript text..."
}
{
  "projectId": "stproj_...",
  "status": "completed",
  "outputReady": true,
  "format": "json",
  "includeWordTimestamps": true,
  "transcript": {
    "text": "Full transcript text...",
    "segments": [
      {
        "start": 0,
        "end": 2.4,
        "text": "First sentence.",
        "words": [{ "word": "First", "start": 0, "end": 0.4 }]
      }
    ]
  },
  "wordTimestamps": [{ "word": "First", "start": 0, "end": 0.4 }]
}