What does it cost to convert Ogg to PNG?

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

How large can the Ogg 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 / Ogg to PNG

Convert Ogg to PNG (single frame)

To convert Ogg to PNG (single frame), send one POST to /v1/video-thumbnail with the Ogg 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 Ogg 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.ogg",
  "time_seconds": 1,
  "format": "png"
}

Response

200 OK
payment-response: <base64 settlement receipt>

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

Source file: av/pair-clip.ogg, 12.3 KB (12,553 bytes). 4 s Ogg file: a 64x36 Theora video stream at 1 fps (a slate field with a small amber square moving right) and a mono 8 kHz FLAC audio track of two 500 Hz triangle beeps, both muxed by ffmpeg, plus a two-cue OGM text subtitle stream added by the generator. The request sets time_seconds to 1. The recorded run returned 705 bytes of PNG, 6% of the source size, with the source read as the ogg 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, 16 Ogg pages carry 3 logical streams: Theora 3.2.1 video of 64 by 36 pixels at 1 frame per second (serial 0), FLAC 1.0 mapping audio at 8,000 Hz with 1 channel (serial 1) and an OGM text stream (serial 2). The end-of-stream pages hold granule positions 2,250 for serial 2, 67 for serial 0 and 32,000 for serial 1. 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

Ogg as a source

An Ogg file opens with the capture pattern OggS, and the container can carry Vorbis, Opus or Theora streams. Grist sniffs that pattern and hands Ogg to three of the conversion services on these pages. Audio conversion decodes the first audio stream, leaving any Theora picture aside. A thumbnail request seeks before opening the input and decodes a single frame from the first video stream, discarding sound. Caption extraction maps a subtitle stream counted from zero among the subtitle streams and serialises it through ffmpeg. Because audio-convert writes its Opus output inside Ogg, a file produced by that service comes back as an Ogg source, not as a separate Opus format. Theora is a lossy video codec, so a frame taken from it carries compression noise into the thumbnail, unlike a clip whose video stream is itself stored losslessly.

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. The Ogg file must carry a video stream: an audio-only Ogg (Vorbis or Opus) has no frame to grab and fails with unprocessable (no_frame).

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