---
title: "Read an uploaded file's details (free)"
method: POST
path: "/v1/ffprobe"
---

# Read an uploaded file's details (free)

`POST /v1/ffprobe`

## Request

- Base URL: `https://api.ffmpeg-micro.com`
- URL: `https://api.ffmpeg-micro.com/v1/ffprobe`
- Auth: HTTP bearer

Run ffprobe on a file you have uploaded and get back what it reports: duration, container format, size, dimensions, frame rate, codecs, and whether it has video and audio. No job is created and no tokens are charged. The file is named by the `gs://` address that `POST /v1/upload/confirm` returned; that response already carries the same details for a file you just uploaded. A public HTTP(S) address is not accepted: upload the file first. Your plan's per-file size limit applies. Rate limited to 30 requests per minute per API key.

## Request body

- object
  - `url` string, required: The `fileUrl` (a `gs://` address) returned by `POST /v1/upload/confirm`.

## Response `200`

What ffprobe reported

- object
  - `url` string: The address as sent
  - `metadata` MediaMetadata: What ffprobe reported about a media file. `duration_seconds`, `format` and `size_bytes` may carry `0` or `"unknown"` when the probe ran but could not determine them (a still image has no duration). `width`, `height`, `fps`, `codec_video`, `codec_audio`, `has_video` and `has_audio` are present only when the probe reported them: a plain audio file has no `width`. Cover art embedded in an audio file is a video stream to ffprobe, so such a file reports `has_video: true` with the artwork's dimensions. `width` and `height` are the stored dimensions, before any rotation the file carries: a phone video shot upright can report 1920 by 1080.
    - `duration_seconds` number
    - `format` string: Container format as ffprobe names it
    - `size_bytes` integer
    - `width` integer: Video width in pixels; absent for audio-only files
    - `height` integer: Video height in pixels; absent for audio-only files
    - `fps` number: Frame rate of the video stream; absent for audio-only files
    - `codec_video` string: Codec of the video stream (e.g. h264); absent when there is none
    - `codec_audio` string: Codec of the audio stream (e.g. aac); absent when there is none
    - `has_video` boolean: Whether the file has a video stream
    - `has_audio` boolean: Whether the file has an audio stream

## Other responses

- `400`: The `url` is missing or not acceptable. `error` is one of `Missing required field: url`, `Unsupported URL` (anything that is not a `gs://` address), `Placeholder bucket name`, `Invalid input` or `Invalid GCS URL`.
- `401`: Missing/invalid API key
- `404`: No uploaded file has that address.
- `422`: `File too large`: the file is over your plan's per-file limit. `Could not read media`: ffprobe could not read it as audio, video or an image.
- `429`: More than 30 requests in a minute from this API key.
- `502`: The probe could not run right now. Nothing was charged; try again.

---

[API](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api.md) · [All operations](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api/revisions/64bb930ff345?raw)