What does it cost to convert MP4 to JPEG?

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

How large can the MP4 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 / MP4 to JPEG

Convert MP4 to JPEG (single frame)

To convert MP4 to JPEG (single frame), send one POST to /v1/video-thumbnail with the MP4 source and "format": "jpeg" in the body. Left out, "format" falls back to its default "png", so a JPEG 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/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 MP4 to JPEG 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.mp4",
  "time_seconds": 1,
  "format": "jpeg"
}

Response

200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/av/pair-clip.mp4",
  "bytes": 11315,
  "container": "mp4",
  "time_seconds": 1,
  "format": "jpeg",
  "width": 64,
  "height": 36,
  "image_bytes": 389,
  "image_base64": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgEBAQEBAUFBQUFBQYGBgYGBgYGBgYG..."
}

Source file: av/pair-clip.mp4, 11 KB (11,315 bytes). 4 s MP4 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 mov_text subtitle stream with two cues. The request sets time_seconds to 1. The recorded run returned 389 bytes of JPEG, 3% of the source size, with the source read as the mp4 container, an image of 64x36 pixels and the frame taken at 1 s. Decoded, the JPEG in image_base64 opens with FF D8 FF E0 00 10 4A 46 49 46 00 01 (ASCII JFIF). Recorded with ffmpeg 8.1.2.

In the sample itself, the ftyp box names major brand isom, minor version 512 and compatible brands isom, iso2 and mp41; the top-level boxes run ftyp, free, mdat and moov, so the moov index comes after the media data; mvhd counts 4,000 ticks at 1,000 per second, 4 s; the 3 tracks are vide with sample entry mp4v, soun with sample entry fLaC and sbtl with sample entry tx3g. In the returned JPEG: after the start-of-image marker comes a 16-byte JFIF APP0 segment, version 1.02, density 1 by 1 with no unit. The segment after it has marker FF DB.

03Format notes

MP4 as a source

MP4 belongs to the ISO base-media family, and Grist recognises it by the ftyp box type at bytes four to eight rather than by a file extension. QuickTime MOV and other files carrying the same box are sniffed as this one container, and the response names it mp4. The container can hold video, audio and text subtitle streams side by side, and each service takes one kind. audio-convert maps the first audio stream and drops the picture. video-thumbnail puts the seek before the input, so it happens at the demuxer and stays cheap in a large file, then decodes exactly one frame from the first video stream. subtitle-extract selects a text track by its zero-based position among subtitle streams. Each ffmpeg run strips container metadata and sets bit-exact flags, so outputs do not carry creation timestamps.

JPEG as a target

image-convert writes JPEG through sharp with options pinned around the caller's quality value. mozjpeg is off, scans are baseline rather than progressive, chroma subsampling is fixed, coding is optimised, and trellis quantisation and overshoot deringing are both disabled. Fixing these settings means the same image, format and quality produce the same bytes on a given build, instead of drifting with a libvips default. The pixel grid is not resized; only codec and container change, and the response reports the width and height of the result. Because withMetadata is never called, EXIF and similar blocks are dropped. An animated input is opened with animation off, so its first frame is the one encoded. Video frames take another road: video-thumbnail decodes one picture and hands it to ffmpeg's mjpeg encoder, which streams it out through image2pipe.

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 MP4 to JPEG?: $0.003 per call, paid in USDC on Base via x402.
How large can the MP4 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.