Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coah80/yoink/llms.txt

Use this file to discover all available pages before exploring further.

Yoink’s transcription feature runs OpenAI Whisper against any media file you upload and produces one of three outputs: a subtitle file you can load in a player, captions burned permanently into the video, or a plain text transcript. Local models (tiny through medium) run entirely on your server with no external API calls. The large model offloads work to the OpenAI Whisper API for maximum accuracy. Transcription is fully asynchronous — the endpoint returns a jobId immediately and processing happens in the background.

​
API endpoint

POST /api/transcribe
Content-Type: multipart/form-data
FieldTypeDefaultDescription
filefile—The video or audio file to transcribe
outputModestringtextsubtitles, captions, or text
modelstringbaseWhisper model to use (see table below)
subtitleFormatstringsrtsrt or ass — only for subtitles mode
languagestringauto2–5 letter language code (e.g. en, ja)
captionSizeint72Font size for captions (40–120)
maxWordsPerCaptionint0Max words per caption segment (1–20, 0 = unlimited)
maxCharsPerLineint0Max characters per caption line (10–80, 0 = unlimited)
minDurationfloat0Minimum caption duration in seconds (0.1–5)
captionGapfloat0Gap between captions in seconds (0–1)
clientIdstring—Optional client ID for job tracking
Response: 
{ "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }

​
Polling the job

1

Start the job

POST /api/transcribe with your file and options. Save the returned jobId.
2

Poll for status

GET /api/job/{jobId}/status
The response includes a status field (processing, complete, or error) and a progress percentage (0–100).
3

Download the result

Once status is complete, fetch your output:
GET /api/job/{jobId}/download
For text mode this returns a .txt file; subtitles returns .srt or .ass; captions returns an .mp4 with captions burned in.

​
Output modes

text

Plain-text transcript saved as <filename>_transcript.txt. Useful for indexing, searching, or feeding into other tools.

subtitles

A standalone subtitle file (.srt or .ass) delivered separately from the video. Load it in any media player that supports external subtitles.

captions

Captions are rendered directly onto the video frames by FFmpeg and exported as <filename>_captioned.mp4. No separate subtitle file is needed.

​
Whisper models

ModelRunsAccuracySpeedRequirement
tinyLocal★☆☆☆☆FastestWhisper installed
baseLocal★★☆☆☆FastWhisper installed
smallLocal★★★☆☆ModerateWhisper installed
mediumLocal★★★★☆SlowWhisper installed
largeOpenAI API★★★★★Fastest (remote)OPENAI_API_KEY
The large model sends audio to the OpenAI Whisper API. You must set the OPENAI_API_KEY environment variable on your Yoink server. If the key is not configured, the job will fail immediately with the message: “Large model requires API configuration. Use a local model (tiny/base/small/medium).”

​
Whisper script resolution

Yoink calls a whisper.py helper script to drive Whisper. It is located in the following order:
  1. The WHISPER_SCRIPT environment variable (explicit path)
  2. whisper.py in the same directory as the Yoink binary
  3. whisper.py on the system PATH
# Override the script location
export WHISPER_SCRIPT=/opt/yoink/scripts/whisper.py

​
Caption styling options

When using subtitles or captions mode, you can control how text is segmented and displayed:
Font size in pixels for rendered captions. Must be between 40 and 120. Default is 72.
captionSize=72
Limits how many words appear in each caption segment. Useful for keeping captions readable. Range: 1–20. Set to 0 to disable.
maxWordsPerCaption=8
Wraps caption text after this many characters. Range: 10–80. Set to 0 to disable.
maxCharsPerLine=42
Minimum time in seconds that each caption segment must be displayed. Prevents very short flashes of text. Range: 0.1–5 seconds.
minDuration=1.5
Adds a pause in seconds between consecutive caption segments. Range: 0–1 second.
captionGap=0.1

​
Language detection

Leave language empty to let Whisper detect the spoken language automatically. Pass an explicit code to skip detection and improve accuracy: 
language=en   # English
language=ja   # Japanese
language=pt   # Portuguese
language=zh   # Chinese
The code must match the regex ^[a-zA-Z]{2,5}$ — 2 to 5 ASCII letters.
Specifying the language explicitly is faster and slightly more accurate, especially for short audio clips where auto-detection can be unreliable.

Build docs developers (and LLMs) love

Get started for freeTalk to us