Videosays - Video to Text Transcription

Videosays Video Transcription

Use npx videosays to submit video links and retrieve transcript text or subtitles. The CLI sends the configured API key and submitted links/share text to Videosays.

Requirements

• Node.js 18 or newer
• npx

Authentication

Before the first transcription in a session, run:

npx videosays whoami

If authentication is missing, run:

npx videosays login

Ask the user to open the printed authorization URL, sign in, and approve the CLI. If the user explicitly provides an API key, run npx videosays login --api-key "$VIDEOSAYS_API_KEY". Never print or reveal the API key.

Single Link

Submit one link:

VIDEOSAYS_CLIENT_SURFACE=agent_skill VIDEOSAYS_CLIENT_NAME=videosays-skill npx videosays transcribe ""

Submission returns quickly. It normally prints:

VIDEOSAYS_TASK_PENDING
task_id=
status=
next=videosays status 

Capture task_id. Wait a reasonable interval, then run the printed one-shot status command:

npx videosays status ""

If the task is still running, status immediately prints its current state and the next command. Repeat status checks until the command prints transcript content or a stable error. Preserve the requested format on status checks:

npx videosays status "" --format timeline
npx videosays status "" --format srt
npx videosays status "" --format vtt

Every accepted transcribe submission creates a new Task ID, including repeated submissions of the same input. Treat transcribe only as creation: capture its returned Task ID and use status for every later check. Never resubmit a link as a status check.

If submission ends with a network error or timeout before printing a Task ID, do not automatically resubmit. Check npx videosays history for a recent matching task first; explain that another submission creates another task if the outcome cannot be recovered.

Multiple Links

When the user provides two or more links, use one server batch. Never build a shell loop, use xargs, start parallel transcribe commands, or submit the links individually.

1. Write one link or share text per line to a temporary text file. Keep duplicate lines when the user requested duplicate work; each line is an independent batch item and Task.
2. Submit once:

VIDEOSAYS_CLIENT_SURFACE=agent_skill VIDEOSAYS_CLIENT_NAME=videosays-skill npx videosays batch links.txt

1. Capture the server-generated batchId from stdout.
2. Wait a reasonable interval, then make a one-shot status request:

npx videosays batch status ""

1. Repeat status checks until the batch reaches completed, partial, failed, or cancelled.

Every batch submission creates a new server Batch ID, even when the file contents are unchanged. Batch submission and status commands return promptly. Do not rerun the input file as a status check, do not invent a Batch ID, and do not use batch resume.

If batch submission ends before printing a Batch ID, do not automatically submit the file again: the server may already have accepted it, and another submission creates another batch. Report the ambiguous outcome and get confirmation before creating a replacement batch.

Videosays creates every batch item as an ordinary Task and runs those Tasks through the normal queue. Each Task must reserve credit atomically before provider submission, so the balance cannot be overspent. If stopReason is insufficient_credits, unstarted Tasks are skipped; ask the user to top up, then after confirmation run:

npx videosays batch continue ""

Then continue using batch status with the same Batch ID.

Optional Interactive Waiting

Only use --wait when a human explicitly wants the terminal to remain attached:

npx videosays transcribe "" --wait
npx videosays batch links.txt --wait

Agents must use the default immediate-return workflow so every tool call produces prompt, structured stdout.

Other Commands

npx videosays balance
npx videosays history
npx videosays batch cancel ""

Errors

Read stderr when a command exits non-zero. Do not treat error output or a pending receipt as transcript content.

Error: 
Code: 
Next: 
Recharge: 

For insufficient_credits, do not repeatedly resubmit. Report the balance issue and recharge URL. For media or link errors such as media_resolve_failed, media_unavailable, or media_inaccessible, ask for another accessible video link.

Links

• Website: https://videosays.com/?utm_source=videosays_skill&utm_medium=agent_skill&utm_campaign=videosays_agent_skill
• API docs: https://videosays.com/docs?utm_source=videosays_skill&utm_medium=agent_skill&utm_campaign=videosays_agent_skill&utm_content=api_docs
• CLI: https://www.npmjs.com/package/videosays