> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Get a media by ID

GET https://api.fastpix.com/v1/on-demand/{mediaId}

By calling this endpoint, you can retrieve detailed information about a specific media item, including its current `status` and a `playbackId`. This is particularly useful for retrieving specific media details when managing large content libraries.

#### How it works

1. Send a GET request to this endpoint. Use the `<mediaId>` you received after uploading the media file.

2. The response includes details about the media:
   * **status** – Indicates whether the media is still *Processing* or has transitioned to *Ready*.
   * **playbackId** – A unique identifier that allows you to stream the media once it is *Ready*.\
     You can construct the stream URL as follows:\
     `https://stream.fastpix.com/<playbackId>.m3u8`

#### Example

If your platform provides users with a dashboard to manage uploaded content, a user might want to check whether a video has finished processing and is ready for playback. You can use the media ID to retrieve the information from FastPix and display it in the user’s dashboard.

Reference: https://fastpix.com/docs/video-on-demand-api/manage-videos/get-media

## Authentication

- `Authorization` header (basic auth, required) — FastPix APIs are secured with Basic Authentication. Use your Access Token ID as the username and Secret Key as the password in the Authorization header of each API request. * Username: Access Token ID * Password: Secret Key Activate your FastPix account to generate your API credentials. See the guide here

## Request

### Path parameters

- `mediaId` (string, required) — The unique identifier assigned to the media when created. The value must be a valid UUID.

## Response

### 200

Get a video media by id

- `success` (boolean, optional) — Demonstrates whether the request is successful or not.
- `data` (GetMediaDetailResponse, optional)

## Types

### GetMediaDetailResponse

- `thumbnail` (string, optional, nullable) — A video thumbnail is a still image that acts as the preview image for your video.
- `id` (string, optional) — The unique identifier assigned to the media when created. The value must be a valid UUID.
- `sourceMediaId` (string, optional) — The source media ID if this media was created from another media (for example, as a clip).
- `workspaceId` (string, optional) — A unique identifier is generated by FastPix for the workspace.
- `streamId` (string, optional) — The ID of the livestream for which the clips were created.
- `metadata` (map from string to string, optional, nullable) — You can search for videos with specific key value pairs using metadata, when you tag a video in "key" : "value" pairs. Dynamic metadata allows you to define a key that allows any value pair. You can have maximum of 255 characters and upto 10 entries are allowed.
- `mediaQuality` (enum, optional) — The quality tier applied to the media.
  - Allowed values: `standard`, `pro`, `premium`
- `creatorId` (string, optional) — The unique identifier of the user who created this media.
- `title` (string, optional, nullable) — Title of the media file.
- `maxResolution` (enum, optional, default: 1080p) — The maximum resolution specified by the user for the media.
  - Allowed values: `2160p`, `1440p`, `1080p`, `720p`, `480p`
- `sourceResolution` (string, optional) — The actual resolution of the uploaded media. This represents the native quality of the source media.
- `status` (enum, optional) — Determines the media's status, which can be one of the possible values.
  - Allowed values: `Created`, `Downloading`, `Downloaded`, `Validating`, `In Queue`, `Processing`, `Ready`, `Failed`
- `mp4Support` (list of GetMediaDetailResponseMp4SupportItems, optional, nullable) — A list of MP4 renditions generated for the media when MP4 support is requested. Each entry represents one downloadable rendition (for example, a capped-4K video file or an audio-only m4a file) along with its generation status. Omitted when no MP4 support has been requested.
- `sourceAccess` (boolean, optional, nullable) — The sourceAccess parameter determines whether the original media file is accessible. Set to true to enable access or false to restrict it.
- `optimizeAudio` (boolean, optional, nullable) — Whether the audio track of the media has been volume-normalized.
- `playbackIds` (list of PlaybackId, optional) — A collection of Playback ID objects utilized for crafting HLS playback URLs.
- `tracks` (list of GetMediaDetailResponseTracksItems, optional) — A media consists of different media tracks, like video, audio, and subtitle, all combined.
- `generatedSubtitles` (list of TracksSubtitles, optional, nullable) — List of generated subtitle tracks associated with the media.
- `summary` (AiSummaryRecord, optional) — AI-generated summary of the media content, if available.
- `chapters` (AiResponseRecord, optional) — AI-generated chapters for the media, if available.
- `namedEntities` (AiResponseRecord, optional) — AI-extracted named entities from the media, if available.
- `moderation` (AiResponseRecord, optional) — Moderation results for the media, if available.
- `isAudioOnly` (boolean, optional, nullable) — Indicates whether the media contains only audio (no video track).
- `subtitleAvailable` (boolean, optional, nullable) — Indicates whether subtitles are available for the media.
- `duration` (double, optional) — The length of the media in seconds, with a maximum allowed duration of 12 hours per individual media.
- `frameRate` (string, optional) — Frame rate quantifies the speed at which frames are displayed per second. It represents the range of frames available for a specific track. The indeterminable frame rate of the input file is indicated by a value of -1.
- `aspectRatio` (string, optional, nullable) — The aspect ratio of a video is a value that describes the relative shape of a video based on its width and height.
- `createdAt` (datetime, optional) — Time the media was created, defined as a localDateTime (UTC Time).
- `updatedAt` (datetime, optional) — Time the media was updated, defined as a localDateTime (UTC Time).

### GetMediaDetailResponseMp4SupportItems

- `type` (enum, optional) — The MP4 rendition type. `capped_4k` is a downloadable MP4 video capped at 4K resolution, `audioOnly` is a downloadable m4a audio-only file.
  - Allowed values: `capped_4k`, `audioOnly`
- `status` (enum, optional) — Generation status of this MP4 rendition.
  - Allowed values: `preparing`, `ready`, `failed`
- `height` (integer, optional, nullable) — Pixel height of the rendition. Omitted for the `audioOnly` type.
- `width` (integer, optional, nullable) — Pixel width of the rendition. Omitted for the `audioOnly` type.
- `ext` (enum, optional) — File extension of the downloadable rendition.
  - Allowed values: `mp4`, `m4a`

### PlaybackId

A collection of Playback ID objects utilized for crafting HLS playback urls.

- `id` (string, optional, nullable) — A unique identifier is generated by FastPix for the playbacks.
- `accessPolicy` (enum, optional) — Access policy for media content
  - Allowed values: `public`, `private`, `drm`
- `accessRestrictions` (PlaybackIdAccessRestrictions, optional) — Controls access based on domains and user agents. Defines a default policy (either "allow" or "deny") and provides lists for explicitly allowed or denied domains and user agents.

### GetMediaDetailResponseTracksItems

- VIDEO_TRACK: VideoTrack
- AUDIO_TRACK: AudioTrack
- SUBTITLE_TRACK: SubtitleTrack

### TracksSubtitles

- `status` (string, optional) — Current status of the generated subtitle track.
- `url` (string, optional, nullable) — URL of the generated subtitle file (VTT). Null while preparing.

### AiSummaryRecord

Represents an AI response record containing status and data for AI-generated features like summary, chapters, named entities, or moderation.

- `status` (string, optional, nullable) — The status of the AI processing (for example, "available", "preparing", "failed").
- `data` (string, optional, nullable) — The AI-generated summary of the media content. This field contains the processed textual output produced by the AI once summarization is complete.

### AiResponseRecord

Represents an AI response record containing status and data for AI-generated features like summary, chapters, named entities, or moderation.

- `status` (string, optional, nullable) — The status of the AI processing (for example, "available", "preparing", "failed").
- `data` (map from string to any, optional, nullable) — The AI-generated content data. Can be a Map, List, or other structured data depending on the AI feature type.

### PlaybackIdAccessRestrictions

Controls access based on domains and user agents. Defines a default policy (either "allow" or "deny") and provides lists for explicitly allowed or denied domains and user agents.

- `domains` (PlaybackIdAccessRestrictionsDomains, optional) — Restrictions based on the originating domain of a request (for example, whether requests from certain websites must be allowed or blocked).
- `userAgents` (PlaybackIdAccessRestrictionsUserAgents, optional) — Restrictions based on the user agent (which is typically a string sent by browsers or bots identifying themselves).

### VideoTrack

A media consists of different media tracks, like video, audio, and subtitle, all combined.

- `id` (string, optional) — FastPix generates a unique identifier for each track.
- `type` (enum, optional) — Defines the type of input. This option is mandatory.
  - Allowed values: `video`
- `width` (double, optional) — Track width denotes the range of widths applicable to a specific track. Currently, this setting can be modified only for video tracks
- `height` (double, optional) — Track height denotes the range of height applicable to a specific track. Currently, this setting can be modified only for video tracks.
- `frameRate` (string, optional) — Frame rate quantifies the speed at which frames are displayed per second. It represents the range of frames available for a specific track. The indeterminable frame rate of the input file is indicated by a value of -1.
- `status` (string, optional) — Indicates the current state of the track. 'available' means the track has been processed successfully and is ready to be used or played.
- `title` (string, optional) — Title of the track.

### AudioTrack

A media consists of different media tracks, like video, audio, and subtitle, all combined.

- `id` (string, optional) — FastPix generates a unique identifier for each track.
- `type` (enum, optional) — Defines the type of input track.
  - Allowed values: `audio`
- `status` (string, optional) — Indicates the current state of the track. 'available' means the track has been processed successfully and is ready to be used or played.
- `title` (string, optional) — Title of the track.
- `languageName` (string, optional) — Name of the language in which the subtitles will be generated.
- `languageCode` (string, optional) — Language codes are concise, standardized symbols that denote languages, utilizing either two or three characters for identification. The language code must be compliant with the BCP 47 standard to ensure compatibility. (for text only).

### SubtitleTrack

A media consists of different media tracks, like video, audio, and subtitle, all combined.

- `id` (string, optional) — FastPix generates a unique identifier for each track.
- `type` (enum, optional) — Defines the type of input track.
  - Allowed values: `subtitle`
- `status` (string, optional) — Indicates the current state of the track. 'available' means the track has been processed successfully and is ready to be used or played.
- `title` (string, optional) — Title of the track.
- `languageName` (string, optional) — Name of the language in which the subtitles will be generated.
- `languageCode` (string, optional) — Language codes are concise, standardized symbols that denote languages, utilizing either two or three characters for identification. The language code must be compliant with the BCP 47 standard to ensure compatibility. (for text only).

### PlaybackIdAccessRestrictionsDomains

Restrictions based on the originating domain of a request (for example, whether requests from certain websites must be allowed or blocked).

- `defaultPolicy` (enum, optional) — Policy action type
  - Allowed values: `allow`, `deny`
- `allow` (list of string, optional) — A list of domains that are explicitly allowed access.
- `deny` (list of string, optional) — A list of domains that are explicitly blocked from accessing the resource.

### PlaybackIdAccessRestrictionsUserAgents

Restrictions based on the user agent (which is typically a string sent by browsers or bots identifying themselves).

- `defaultPolicy` (enum, optional) — Policy action type
  - Allowed values: `allow`, `deny`
- `allow` (list of string, optional) — A list of specific user agents that are allowed to access the resource.
- `deny` (list of string, optional) — A list of specific user agents that are blocked.

## Examples

**Response**

```json
{
  "success": true,
  "data": {
    "thumbnail": "https://images.fastpix.com/837f028b-dcaf-4c23-b368-3748641f74ac/thumbnail.png",
    "id": "cfeec1a3-6cbd-40df-a425-2ed7f8f72ced",
    "workspaceId": "6dc2b4e0-0615-42fd-a580-1f4aad932dfe",
    "metadata": {
      "key1": "value1"
    },
    "mediaQuality": "standard",
    "maxResolution": "1080p",
    "sourceResolution": "1080p",
    "status": "Ready",
    "mp4Support": [
      {
        "type": "capped_4k",
        "status": "ready",
        "height": 1080,
        "width": 1920,
        "ext": "mp4"
      },
      {
        "type": "audioOnly",
        "status": "ready",
        "ext": "m4a"
      }
    ],
    "sourceAccess": false,
    "playbackIds": [
      {
        "id": "837f028b-dcaf-4c23-b368-3748641f74ac",
        "accessPolicy": "public",
        "accessRestrictions": {
          "domains": {
            "defaultPolicy": "allow",
            "allow": [],
            "deny": []
          },
          "userAgents": {
            "defaultPolicy": "allow",
            "allow": [],
            "deny": []
          }
        }
      }
    ],
    "tracks": [
      {
        "id": "f301a2a1-b40d-40fa-b419-4d0cd92a62f8",
        "type": "video",
        "width": 1920,
        "height": 1080,
        "frameRate": "30/1",
        "status": "available"
      }
    ],
    "isAudioOnly": false,
    "subtitleAvailable": true,
    "duration": 10.5,
    "aspectRatio": "16:9",
    "createdAt": "2025-01-09T06:44:44.617138Z",
    "updatedAt": "2025-01-09T06:44:53.742648Z"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6"

response = requests.get(url, auth=("<username>", "<password>"))

print(response.json())
```

```javascript
const url = 'https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6';
const credentials = btoa("<username>:<password>");

const options = {method: 'GET', headers: {Authorization: `Basic ${credentials}`}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6"

	req, _ := http.NewRequest("GET", url, nil)

	req.SetBasicAuth("<username>", "<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request.basic_auth("<username>", "<password>")

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6")
  .basicAuth("<username>", "<password>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6', [
  'headers' => [
  ],
    'auth' => ['<username>', '<password>'],
]);

echo $response->getBody();
```

```csharp
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let credentials = Data("<username>:<password>".utf8).base64EncodedString()

let headers = ["Authorization": "Basic \(credentials)"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```