What does it cost to convert MKV to PNG?

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

How large can the MKV 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.

catalogue / tools / Audio & video / MKV to PNG

Convert MKV to PNG (single frame)

To convert MKV to PNG (single frame), send one POST to /v1/video-thumbnail with the MKV source and "format": "png" in the body. "png" is the schema default of "format", so the field may also be left out. 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/video-thumbnail
Price: $0.003 per call
Service: video-thumbnail
Docs: /docs/video-thumbnail

01Limits

Limit	Value
Largest source file	200 MB (209,715,200 bytes)
Timeout	60 s
Source formats	AVI, MKV, MP4, Ogg
Output formats	JPEG, PNG
Option time_seconds	default 0

02Example

A real MKV to PNG run of video-thumbnail.

Request

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

{
  "url": "https://grist.tools/samples/av/pair-clip.mkv",
  "time_seconds": 1,
  "format": "png"
}

Response

200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/av/pair-clip.mkv",
  "bytes": 10531,
  "container": "matroska",
  "time_seconds": 1,
  "format": "png",
  "width": 64,
  "height": 36,
  "image_bytes": 186,
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAAAkCAIAAAC2bqvFAAAACXBIWXMAAAABAAAA..."
}

Source file: av/pair-clip.mkv, 10.3 KB (10,531 bytes). 4 s Matroska file made by ffmpeg: a 64x36 PNG video stream at 1 fps (a slate field with a small amber square moving right), a mono 8 kHz FLAC audio track of two 500 Hz triangle beeps, and an English SubRip subtitle stream with two cues. The request sets time_seconds to 1. The recorded run returned 186 bytes of PNG, 2% of the source size, with the source read as the matroska container, an image of 64x36 pixels and the frame taken at 1 s. Decoded, the PNG in image_base64 opens with 89 50 4E 47 0D 0A 1A 0A 00 00 00 0D (ASCII PNG). Recorded with ffmpeg 8.1.2.

In the sample itself, the EBML header names DocType matroska, version 4, readable by a version 2 parser; Segment Info sets a timestamp scale of 1,000,000 ns and a duration of 4,000 ticks, 4 s, with Lavf as the muxing application; the Tracks element lists codec IDs V_MS/VFW/FOURCC (video, language und), A_FLAC (audio, language und) and S_TEXT/UTF8 (subtitle, language eng). In the returned PNG: its IHDR chunk declares 64 by 36 pixels, 8-bit truecolour RGB and no interlacing. The next chunk is pHYs.

03Format notes

MKV as a source

Matroska files begin with the EBML magic 1A 45 DF A3, and WebM uses the same signature, so the sniffer treats both as a single container and reports it as matroska in the container field of each response. Matroska is built from tracks that ffmpeg can address independently. When audio is the target, the first audio track is decoded and any picture is ignored. For a still frame, the requested timestamp is sought at the demuxer level before one picture is decoded, with sound excluded. A subtitle track is chosen by its index counted among subtitle tracks only, starting from zero, and an index that matches nothing is refused rather than answered with an empty file. SubRip or WebVTT text written by ffmpeg comes back together with a cue count taken from the timing arrows in that text.

PNG as a target

PNG output is lossless, so image-convert ignores the quality value when PNG is requested. Its encoder options are pinned: the maximum zlib compression level, a fixed effort, adaptive filtering off, palette quantisation off and no interlacing, so identical pixels always deflate to identical bytes. Dimensions are kept and reported in the response, and metadata is stripped. Vector input takes a separate service: svg-to-png renders the document at a caller-set density, which drives the natural raster size, and an optional width or height fits the render inside that box with the lanczos3 kernel, keeping the aspect ratio, before the same pinned PNG options apply. video-thumbnail writes PNG by default through ffmpeg's png encoder; when a width is requested, the height follows the aspect ratio and is rounded to an even number.

Note: The answer is one frame of the video, taken at the timestamp you choose, not the whole video.

04Errors

Code	HTTP
`invalid_input`	`400`
`blocked_target`	`403`
`unreachable_target`	`424`
`upstream_timeout`	`424`
`unsupported_content_type`	`415`
`too_large`	`413`
`unprocessable`	`422`
`internal`	`500`

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

05Questions

What does it cost to convert MKV to PNG?: $0.003 per call, paid in USDC on Base via x402.
How large can the MKV 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.