Convert AVI to WebVTT (subtitle track)

To convert AVI to WebVTT (subtitle track), send one POST to /v1/subtitle-extract with the AVI source and "to": "vtt" in the body. Left out, "to" falls back to its default "srt", so a WebVTT request has to send it. Each call costs $0.003 in USDC on Base via x402, with no account and no API key. The source file can be up to 200 MB.

Endpoint

POST /v1/subtitle-extract

Price

$0.003 per call

Service

subtitle-extract

Docs

/docs/subtitle-extract

01Limits

02Example

No real AVI to WebVTT example: ffmpeg's AVI muxer writes no text subtitle stream (only DivX XSUB bitmaps), so there is no real AVI with captions to extract. The example below is the service's own.

The published example of subtitle-extract, verbatim. Its sample file may be in another source format than AVI. Send to: "vtt" to get WebVTT.

POST /v1/subtitle-extract
content-type: application/json
payment-signature: <base64 x402 payload>

{
  "url": "https://grist.tools/samples/av/subtitle-movie.mkv",
  "stream": 0,
  "to": "srt"
}

200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/av/subtitle-movie.mkv",
  "bytes": 1486,
  "container": "matroska",
  "stream_index": 0,
  "format": "srt",
  "cue_count": 2,
  "subtitle": "1\n00:00:00,500 --> 00:00:02,000\nThe kettle starts to hum.\n\n2\n00:00:02,500 --> 00:00:04,000\nSteam rises from the spout.\n\n"
}

03Format notes

AVI as a source

AVI is a RIFF container whose form type at byte eight is the four characters AVI followed by a space. Grist checks that form type, not the extension, before ffmpeg sees the file. Three of the conversion services on these pages accept it. audio-convert reads the first audio stream and ignores video; video-thumbnail seeks at the demuxer and decodes exactly one frame with audio disabled; subtitle-extract maps a subtitle stream by its zero-based index. That last route has a practical gap: ffmpeg's AVI muxer writes no text subtitle stream, only DivX XSUB bitmaps, so no real AVI with text captions could be produced for an example, and the AVI subtitle pages carry none. An AVI whose subtitle index matches nothing is refused rather than answered with an empty result. Each response reports the sniffed container as avi alongside the size of the fetched file.

WebVTT as a target

subtitle-convert writes WebVTT as the WEBVTT header, a blank line, then cues with dotted timestamps in HH:MM:SS.mmm form. WebVTT is that service's default destination. Output is rebuilt from each cue's start, end and text, so SubRip index numbers disappear and no positioning settings are added. Text subtitle tracks inside media containers take a different writer: subtitle-extract passes them through ffmpeg's webvtt muxer, and in the recorded extraction results that muxer prints timestamps without an hour component. Metadata is stripped and bit-exact flags are set on that route, so the same stream yields the same text for a pinned ffmpeg. Both routes end in the same format, while the serialiser, and therefore the exact timestamp layout, depends on whether the captions started as a file or as a track. Nothing follows the end timestamp on a timing line, because subtitle-convert writes no cue settings, and no identifier precedes a cue.

Note: The container must carry a text subtitle track; image-based subtitles cannot be turned into text.

04Errors

When each is raised, and what it means for payment: /docs/subtitle-extract.

05Questions

What does it cost to convert AVI to WebVTT?

$0.003 per call, paid in USDC on Base via x402.

How large can the AVI file be?

Up to 200 MB (209,715,200 bytes). Past a limit the call answers too_large (413).

What happens if the conversion fails?

The tool answers with a typed JSON error from the errors table. Payment is settled only after the tool has produced its result; a call that fails inside the tool is never settled.

06Related

• Audio & video guide
• MKV to WebVTT
• MP4 to WebVTT
• Ogg to WebVTT
• SRT to WebVTT