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. Read the Videosays Skill workflow.

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

Browser-authorized CLI login creates a dedicated API key and saves it locally. Create separate labeled keys for other integrations in Agent / API. Raw keys are shown once; they can expire or be revoked. API keys are limited to transcription and credit scopes, while billing and account management require a Better Auth bearer token.

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
Idempotency-Key: <uuid>

{
  "input": "https://www.tiktok.com/@creator/video/123456",
  "options": { "duplicatePolicy": "reuse" }
}

Create a resumable batch (up to 100 items)

POST https://api.videosays.com/api/v1/batches
Idempotency-Key: <uuid>

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

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 lightweight batch status

GET https://api.videosays.com/api/v1/batches/:batchId?view=status

Continue batch after top-up

POST https://api.videosays.com/api/v1/batches/:batchId/continue?view=status

Get credit balance

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

Get task history

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

Response formats

Send a UUID Idempotency-Key with every submission. Same-key retries replay the same request; reusing the key for different input returns 409. Repeated videos reuse this account’s active or completed task by default. Set options.duplicatePolicy to force_new only for a fresh, normally billed transcription; the web dashboard uses prompt.

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`	The API key or bearer token is missing or invalid.
`402`	Insufficient credits for an explicit force_new admission or batch continuation.
`400`	Invalid request body or parameters.
`422`	The input platform or link is unsupported.
`404`	Task was not found or does not belong to the current account.
`409`	Idempotency conflict or a completed duplicate needs a reuse decision.
`429`	Too many requests. Retry later.
`500`	Server or provider error. Retry later if the source link is still valid.