Docs

Videosays API and CLI docs

Technical reference for API keys, CLI commands, asynchronous transcription tasks, responses, and errors.

Using an AI agent? Start with the AI agents page.

Overview

Videosays turns supported public video links or share text into transcript text, timestamped timelines, SRT subtitles, or VTT subtitles. Use the web dashboard for manual work, the CLI for local automation and agent runtimes, or the REST API for product integrations.

Want to submit a task directly from a video page? See the Videosays Chrome extension.

Authentication

CLI and API requests use your Videosays API key. The CLI can create and save it automatically after browser authorization.

export VIDEOSAYS_API_KEY="vs_xxxxx"

CLI

Command	Description
`npx videosays login`	Authorize in the browser and save the API key
`npx videosays whoami`	Check whether the CLI is authenticated
`npx videosays transcribe "<video-link>"`	Submit immediately and return a Task ID
`npx videosays status "<task-id>" --format srt`	Check once and return the SRT result when ready
`npx videosays batch links.txt`	Create up to 100 items and return a Batch ID immediately
`npx videosays batch status "<batch-id>"`	Inspect aggregate batch progress in one request
`npx videosays batch continue "<batch-id>"`	Continue unprocessed items after topping up
`npx videosays balance`	Check available minutes
`npx videosays history`	View recent task history

REST API

Download OpenAPI spec Download Postman collection

Create transcription task

POST https://api.videosays.com/api/v1/transcribe

{
  "input": "https://www.tiktok.com/@creator/video/123456"
}

Create a resumable batch (up to 100 items)

POST https://api.videosays.com/api/v1/batches

{
  "items": [
    "https://www.douyin.com/video/123",
    "https://www.youtube.com/watch?v=abc"
  ]
}

Batch creation atomically creates ordinary Tasks and sends them through the same queue as single submissions. Each Task reserves credit atomically before provider submission; if one cannot reserve enough credit, unstarted Tasks are skipped. Top up and continue the same batch.

Get task status and result

GET https://api.videosays.com/api/v1/transcribe/:taskId

Get batch status

GET https://api.videosays.com/api/v1/batches/:batchId

Continue batch after top-up

POST https://api.videosays.com/api/v1/batches/:batchId/continue

Get credit balance

GET https://api.videosays.com/api/v1/credits

Get task history

GET https://api.videosays.com/api/v1/history

Response formats

Every accepted submission creates a new Task ID (or Batch ID) and returns immediately. Poll the status endpoint with that returned ID until it reaches a terminal state; submitting the input again creates another resource.

text: plain transcript, default
timeline: timestamped transcript segments
srt: SRT subtitle content
vtt: VTT subtitle content

{
  "taskId": "uuid",
  "status": "completed",
  "video": {
    "platform": "tiktok",
    "durationSeconds": 72
  },
  "billing": {
    "creditMinutes": 1.2
  },
  "result": {
    "text": "Transcript text...",
    "segments": null
  },
  "error": null
}

Errors

`401`	API key is missing or invalid.
`402`	Insufficient credits. Buy minutes before submitting more work.
`400`	Invalid request body or unsupported input.
`404`	Task was not found or does not belong to the current account.
`429`	Too many requests. Retry later.
`500`	Server or provider error. Retry later if the source link is still valid.