Scriptivox logoScriptivox

    Get started

    OverviewQuickstartAuthenticationPricing

    API Reference

    TranscribeFile UploadGet ResultBalanceError CodesRate LimitsFormatsLanguages

    Guides

    WebhooksCLIMCP ServerVersioning

    Use Cases

    Folder Watcher
    Scriptivox logoScriptivoxAPI Documentation

    CLI

    @scriptivox-api/cli is the official command-line client for the Scriptivox transcription API. It transcribes recorded audio and video from a shell or a script — 119 languages, speaker diarization, word-level timestamps, and SRT / WebVTT / plain-text export.

    It is a peer of the MCP server: same API, different transport. Use the CLI when a human or a shell script is driving; use MCP when a model is.

    npm: @scriptivox-api/cli · Command: scriptivox-api

    Install

    bash
    npm install -g @scriptivox-api/cli
    

    # or run it without installing
    npx @scriptivox-api/cli --help

    Node 18 or newer. Zero runtime dependencies — nothing is pulled in at install time beyond the package itself.

    Authenticate

    Create a key at /keys and add credit at /billing.

    bash
    export SCRIPTIVOX_API_KEY=sk_live_...

    Or pass --api-key per command. See Authentication for the header details the CLI handles for you.

    The API is billed separately from the web app

    A subscription on scriptivox.com grants no API credit. API usage draws down a prepaid balance at $0.20 per hour of audio. That is why the package is @scriptivox-api/cli and the command is scriptivox-api rather than scriptivox — the name is a reminder of which product you are spending.

    Commands

    Every command maps one-to-one onto an operation in the OpenAPI specification.

    bash
    # Transcribe a public URL and wait for the result
    scriptivox-api transcribe https://example.com/meeting.mp3 --language en --diarize --wait
    

    # Upload a local file, transcribe it, wait
    scriptivox-api transcribe ./interview.m4a --diarize --speakers 2 --wait
    

    # Export captions — stdout is clean, progress goes to stderr
    scriptivox-api get 4f3c... --format srt --max-words 3 > interview.srt
    scriptivox-api get 4f3c... --format vtt --speakers-in-captions true > interview.vtt
    

    # Inspect and manage jobs
    scriptivox-api status 4f3c...
    scriptivox-api list --status completed --limit 20 --json
    scriptivox-api cancel 4f3c...
    scriptivox-api delete 4f3c...
    

    # Check the balance
    scriptivox-api balance

    scriptivox-api --help lists every flag.

    Scripting

    Structured output goes to stdout, progress and diagnostics to stderr, so a redirect produces a clean file even while the command is reporting status. --json puts JSON on stdout and silences progress entirely.

    Exit codes are part of the contract:

    CodeMeaning
    0Success
    1Usage error — bad arguments, missing API key, unreadable file
    2API error — the machine-readable error code is printed on stderr
    bash
    if ! scriptivox-api transcribe ./call.mp3 --wait --json > result.json; then
      echo "transcription failed with exit $?" >&2
    fi

    The exit-code contract is guarded by an offline test suite that never touches the network, so a refactor cannot quietly change a code that scripts depend on.

    Things worth knowing

    • transcribe returns before the work is done. Without --wait you get a job ID; input problems — unreachable URL, unsupported media, audio too long — surface later on status, as status: failed with an error.code. Check the poll path, not just the submit call.
    • Pass --language when you know it. Auto-detection works most of the time but mis-routes short clips, code-switched audio, and files that open with music. It is also faster, because the model skips its detection pass.
    • --speakers needs --diarize. It is a prior, not a hard cap: asking for 5 may yield 6.
    • Failed and cancelled jobs are free. The reserved balance is released.
    • --idempotency-key makes retries safe. The same key with the same body replays the cached response for 24 hours instead of starting a second, separately-billed job.

    Scope

    The CLI talks to https://api.scriptivox.com/v1 and nothing else. There is no session login, no cookie handling, and no access to the web app or the developer dashboard — an sk_live_… key is the only credential it understands.

    MIT licensed. Bug reports and feature requests: support@scriptivox.com.