Media

Media Items

endpoints

_10
# Media
_10
POST https://api.ittybit.com/media
_10
GET https://api.ittybit.com/media
_10
_10
# Media Item
_10
GET https://api.ittybit.com/media/:id
_10
PATCH https://api.ittybit.com/media/:id
_10
DELETE https://api.ittybit.com/media/:id

Media Items are the core objects in Ittybit.

They act as containers for your related media assets.

The simplest Media Item could contain just a single image. Whilst more complex examples might include multiple audio and video tracks, as well as multiple intelligence items and custom metadata.

Each new upload or ingested file creates a new Media Item.

Sources

A Source is a single variant of the original media. Every Media Item will have at least one Source, which is a direct copy of the original media.

Media Items can contain any number of additional Sources, enabling you to store multiple variants of the original media for different devices and use cases, together in a single Media Item resource.

Tracks

Additionally Media with a kind of video may have one or more Tracks.

Tracks provide additional features which can be used by Players to provide a more engaging experience for your viewers:

  • Subtitles
  • Chapters
  • Thumbnails

Intelligence

Media Items can also contain one or more Intelligence items.

Intelligence items are JSON-formatted objects containing rich data extracted from the media file by Ittybit's AI models:

  • Description: A visual description of images or videos useful for SEO and accessibility.
  • Summary: A text summary of video and audio content, including suggested title, preview paragraph, and tags.
  • Speech: Highly accurate speech-to-text transcription with word-level timestamps and optional speaker identification.
  • NSFW Detection: Scan media for any nudity, violence, or other explicit content.

Metadata

Media Items can also contain custom metadata in a JSON object containing your own key-value pairs.

Metadata is useful for storing additional information you need to associate with the media. Other customer use metadata to store things like:

  • User ID of the user who uploaded the media
  • Content ID of an article the media is associated with
  • Expiry Date for media that can be periodically cleaned up
  • Custom Tags for easy search and filtering

Examples

Example A

A Media Item with a kind of image might have two Sources:

  • one Source with a format of webp
  • another Source with a format of jpeg

Example B

A Media Item with a kind of video might have three Sources:

  • one Source with a height of 1080px
  • one Source with a height of 480px
  • one Source with format of jpeg and label of thumbnail

Example C

A Media Item with a kind of video might have:

  • one Source with a format of mp4
  • another Source with a format of jpeg
  • one Intelligence with a kind of speech
  • another Intelligence with a kind of objects
  • one Track with a kind of subtitles

Endpoints

Create Media Item

request.js
request.sh

_19
const response = await fetch(`https://api.ittybit.com/media`, {
_19
headers: {
_19
Method: "POST",
_19
Authorization: `Bearer ${ITTYBIT_API_KEY}`,
_19
"Content-Type": "application/json",
_19
body: JSON.stringify({
_19
url: "https://yourbucket.s3.amazonaws.com/your-file.mp4?signature=1234567890&expires=1234567890",
_19
filename: "new-filename.mp4",
_19
folder: "your/folder/path",
_19
title: "My Video Upload",
_19
metadata: {
_19
original_filename: "your-file.mp4",
_19
user_id: "123",
_19
source: "YourApp/iOS",
_19
purpose: "profile_video",
_19
},
_19
}),
_19
},
_19
});

Endpoint

https://api.ittybit.com/media

HTTP Method

POST

Description

Creates a new media item by ingesting a file from a url.

Note: To upload a file directly to Ittybit, including via secure client-side uploads, you can use the Uploads API.

response.json

_48
{
_48
"meta":{
_48
"id": "req_abcdefgh1234",
_48
"method": "POST",
_48
"host": "https://api.ittybit.com",
_48
"path": "/media",
_48
"version": "2024-08-21",
_48
"status": 200,
_48
"org_id": "org_abcdefgh1234",
_48
"project_id": "prj_abcdefgh5678",
_48
"type": "object"
_48
},
_48
"data": {
_48
"id": "med_abcdefgh5678",
_48
"object": "media",
_48
"title": "My Video Upload",
_48
"folder": "your/folder/path",
_48
"kind": "video",
_48
"width": 1920,
_48
"height": 1080,
_48
"duration": 60.0,
_48
"fps": 30.0,
_48
"filesize": 12345678,
_48
"total_filesize": 12345678,
_48
"sources": [
_48
// ... Source object
_48
// https://ittybit.com/docs/api/sources
_48
],
_48
"tracks": [],
_48
"intelligence": [],
_48
"original": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/new-filename.mp4",
_48
"placeholder": "data:image/png;base64,aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUSZwcD15Z1VJY21samEzSnZiR3clM0Q=",
_48
"background": "#FF94A4",
_48
"metadata": {
_48
"original_filename": "your-file.mp4",
_48
"user_id": "123",
_48
"source": "YourApp/iOS",
_48
"purpose": "profile_video"
_48
},
_48
"status": "active",
_48
"created": "2024-08-30T15:00:00Z",
_48
"updated": "2024-08-30T15:00:01Z",
_48
},
_48
"links": {
_48
"self": "https://api.ittybit.com/media/med_abcdefgh5678",
_48
"parent": "https://api.ittybit.com/media",
_48
}
_48
}

Body Parameters

  • url string (required)

    A URL to the file to ingest. The file must be publicly accessible or have a signed URL with an expiry > 10 minutes in the future.

  • title string

    A title for the media item. This can be used to identify the media item in the media library. Defaults to the filename.

  • filename string

    The filename will be used in the URL that accesses the original source for the media. It can contain letters, numbers, underscores, and hyphens. If not provided, we will use the file's id and an extension based on the filetype e.g. /[folder_path]/file_abcdefgh1234.mp4.

    Note that the filename must be unique within the given folder unless the overwrite parameter is set to true.

  • folder string

    An optional folder value can be provided to help you organise your media, or to match the folder structure of an existing media library. Folder values can be a path or a single folder name and will be used in the URLs used to access your media files. If not provided, we will use the default folder for your project e.g. /media/[filename].

  • overwrite boolean

    If true, the media item will be created even if another file with the same filename already exists in the given folder. Note that overwritten files are not deleted and can be accessed (or renamed or deleted) via the Files API. Defaults to false.

  • metadata object

    A set of key-value pairs to store with the media item. Values must be strings. In addition, nested objects are not supported – if you have an interesting use case for this, please let us know about it.

List Media Items

request.js
request.sh

_10
const response = await fetch(`https://api.ittybit.com/media`, {
_10
headers: {
_10
Authorization: `Bearer ${ITTYBIT_API_KEY}`,
_10
},
_10
});

Endpoint

https://api.ittybit.com/media

HTTP Method

GET

Description

Returns a list of all media items in your project.

response.json

_56
{
_56
"meta":{
_56
"id": "req_abcdefgh1234",
_56
"org_id": "org_abcdefgh1234",
_56
"project_id": "prj_abcdefgh1234",
_56
"method": "GET",
_56
"host": "https://api.ittybit.com",
_56
"path": "/media",
_56
"query": {
_56
"your_custom_key": "Your custom value",
_56
},
_56
"version": "2024-08-21",
_56
"status": 200,
_56
"type": "list",
_56
"total": 120,
_56
"limit": 12,
_56
"page": 1,
_56
"pages": 10
_56
},
_56
"data": [
_56
{
_56
"id": "med_abcdefgh1234",
_56
"object": "media",
_56
"kind": "video",
_56
"width": 1920,
_56
"height": 1080,
_56
"duration": 60,
_56
"fps": 30,
_56
"filesize": 12345678,
_56
"sources": [
_56
// ... Source objects
_56
// https://ittybit.com/docs/api/sources
_56
],
_56
"tracks": [
_56
// ... Track objects
_56
// https://ittybit.com/docs/api/tracks
_56
],
_56
"intelligence": [
_56
// ... Intelligence objects
_56
// https://ittybit.com/docs/api/intelligence
_56
],
_56
"metadata": {
_56
"your_custom_key": "Your custom value",
_56
"fav_number": "69",
_56
"is_nice": "true"
_56
},
_56
"created": "2024-08-30T13:00:00Z",
_56
"updated": "2024-08-30T13:01:00Z",
_56
}
_56
],
_56
"links": {
_56
"self": "https://api.ittybit.com/media",
_56
"next": "https://api.ittybit.com/media?page=2",
_56
"prev": null,
_56
}
_56
}

Query Parameters

  • page integer

    The page number to return. Default is 1.

  • limit integer

    The number of items to return per page. Default is 12. Maximum is 100.

  • sort string

    The field to sort by. Default is created. Possible values are created, updated, filesize, duration, width, height, fps, or filename.

  • order string

    The order to sort by. Default is desc. Possible values are asc, desc.

  • kind string

    The kind of media to return. Possible values are image, video, audio.

  • metadata.KEY string

    Filter media by metadata values. Multiple parameters can be chained, and results will contain only the results that match all the provided metadata key-value pairs e.g. to find all media with a user_id of 123 and a source of YourApp/iOS, you can add the query params ?metadata.user_id=123&metadata.source=YourApp/iOS. Values are case-sensitive, will be URL-decoded for comparison, and must be an exact string match.

View Media Item

request.js
request.sh

_10
const response = await fetch(`https://api.ittybit.com/media/med_abcdefgh1234`, {
_10
headers: {
_10
Authorization: `Bearer ${ITTYBIT_API_KEY}`,
_10
},
_10
});

Endpoint

https://api.ittybit.com/media/:id

HTTP Method

GET

Description

Returns the details for a single media item.

response.json

_56
{
_56
"meta":{
_56
"id": "req_abcdefgh1234",
_56
"org_id": "org_abcdefgh1234",
_56
"project_id": "prj_abcdefgh1234",
_56
"method": "GET",
_56
"host": "https://api.ittybit.com",
_56
"path": "/media/med_abcdefgh1234",
_56
"version": "2024-08-21",
_56
"status": 200,
_56
"type": "object"
_56
},
_56
"data": {
_56
"id": "med_abcdefgh1234",
_56
"object": "media",
_56
"title": "My Video Upload",
_56
"folder": "med_abcdefgh1234",
_56
"kind": "video",
_56
"width": 1920,
_56
"height": 1080,
_56
"duration": 60,
_56
"fps": 30,
_56
"filesize": 12345678,
_56
"total_filesize": 24681357,
_56
"sources": [
_56
// ... Source objects
_56
// https://ittybit.com/docs/api/sources
_56
],
_56
"tracks": [
_56
// ... Track objects
_56
// https://ittybit.com/docs/api/tracks
_56
],
_56
"intelligence": [
_56
// ... Intelligence objects
_56
// https://ittybit.com/docs/api/intelligence
_56
],
_56
"original": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/new-filename.mp4",
_56
"poster": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/poster.jpg",
_56
"speech": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/speech.json",
_56
"subtitles": "https://prj_abcdefgh1234.ittybitcdn.com/your/folder/path/subtitles.srt",
_56
"placeholder": "data:image/png;base64,aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUSZwcD15Z1VJY21samEzSnZiR3clM0Q=",
_56
"background": "#FF94A4",
_56
"metadata": {
_56
"original_filename": "your-file.mp4",
_56
"user_id": "123",
_56
"source": "YourApp/iOS",
_56
"purpose": "profile_video"
_56
},
_56
"created": "2024-08-30T13:00:00Z",
_56
"updated": "2024-08-30T13:01:00Z",
_56
},
_56
"links": {
_56
"self": "https://api.ittybit.com/media/med_abcdefgh1234",
_56
"parent": "https://api.ittybit.com/media",
_56
}
_56
}

Response Parameters

  • id string

    Unique identifier for the media item.

  • object string

    The type of object. Always media.

  • title string

    The title of the media item or null if no title has been set.

  • folder string

    The folder the media item is stored in or null if no folder has been set.

  • kind string

    The kind of the original file. Possible values are image, video, audio.

  • width integer

    The width of the original file in pixels.

  • height integer

    The height of the original file in pixels.

  • duration number

    The duration of the original file in seconds (for video, audio, and animated images).

  • fps number

    The frames per second of the original file (for video and animated images).

  • filesize integer

    The size of the original file in bytes.

  • total_filesize integer

    The total size of all the media files in the media item. This is the sum of the filesizes of all source, track, and intelligence files.

  • sources array

    An array of Source objects that describe the different variants of the media that have been created.

  • tracks array

    An array of Track objects that describe additional metadata files that have been created for the media. This is only present for media with a kind of video or audio.

  • intelligence array

    An array of Intelligence objects that describe the rich data that has been extracted from the media.

  • original string

    The URL to the original asset.

  • ... urls strings

    If the media item has additional sources, tracks, or intelligence, and any of those files have a label, then the url to the file will be included in the top-level media object with the label as the key e.g. a source with the label poster will be included as poster: https://[... url to file].

  • placeholder string

    A base64-encoded placeholder image for the media item. This is only present for media with a kind of image or video.

  • background string

    The dominant color in the original asset, in hexadecimal format e.g. #FF94A4. This is only present for media with a kind of image or video.

  • metadata object

    A JSON object containing key-value pairs forany custom metadata you have attached to the media item.

  • created datetime

    The date and time the media item was created. ISO 8601 format.

  • updated datetime

    The date and time the media item was last updated. ISO 8601 format.

Update Media Item

request.js
request.sh

_15
const response = await fetch(`https://api.ittybit.com/media/med_abcdefgh1234`, {
_15
headers: {
_15
Method: "PATCH",
_15
Authorization: `Bearer ${ITTYBIT_API_KEY}`,
_15
"Content-Type": "application/json",
_15
body: JSON.stringify({
_15
title: "My New Title",
_15
folder: "new/folder/path",
_15
metadata: {
_15
"new_value": "New value",
_15
"purpose": null
_15
}
_15
}),
_15
},
_15
});

Endpoint

https://api.ittybit.com/media/:id

HTTP Method

PATCH

Description

Update a media item's title, folder, and/or metadata.

response.json

_51
{
_51
"meta":{
_51
"id": "req_abcdefgh1234",
_51
"org_id": "org_abcdefgh1234",
_51
"project_id": "prj_abcdefgh5678",
_51
"method": "PATCH",
_51
"host": "https://api.ittybit.com",
_51
"path": "/media",
_51
"version": "2024-08-21",
_51
"status": 200,
_51
"type": "object"
_51
},
_51
"data": {
_51
"id": "med_abcdefgh1234",
_51
"object": "media",
_51
"title": "My New Title",
_51
"folder": "new/folder/path",
_51
"kind": "video",
_51
"width": 1920,
_51
"height": 1080,
_51
"duration": 60,
_51
"fps": 30,
_51
"filesize": 12345678,
_51
"total_filesize": 24681357,
_51
"sources": [
_51
// ... Source object
_51
// https://ittybit.com/docs/api/sources
_51
],
_51
"tracks": [
_51
// ... Track object
_51
// https://ittybit.com/docs/api/tracks
_51
],
_51
"intelligence": [
_51
// ... Intelligence object
_51
// https://ittybit.com/docs/api/intelligence
_51
],
_51
"metadata": {
_51
"original_filename": "your-file.mp4",
_51
"user_id": 123,
_51
"source": "YourApp/iOS",
_51
"new_value": "New value"
_51
},
_51
"status": "active",
_51
"created": "2024-08-30T13:00:00Z",
_51
"updated": "2024-08-30T14:00:00Z",
_51
},
_51
"links": {
_51
"self": "https://api.ittybit.com/media/med_abcdefgh1234",
_51
"parent": "https://api.ittybit.com/media",
_51
}
_51
}

Body Parameters

  • title string

    A new title for the media item.

  • folder string

    A new folder for the media item. All Source, Intelligence, and Track files will be moved to the new folder. Note that existing links will need to be updated. Filenames can be updated by using the Files API.

  • overwrite boolean

    If true, the folder will be updated even if files already exist in the given folder with the same filename as files in the media item. Note that overwritten files are not deleted and can be accessed (or renamed or deleted) via the Files API. Defaults to false.

  • metadata object

    The new metadata to attach to the media item. Values will be merged with existing values. To remove a value you can set it to null. To remove all metadata, you can pass an empty object: {}.

Delete Media Item

request.js
request.sh

_10
const response = await fetch(`https://api.ittybit.com/media/med_abcdefgh1234`, {
_10
headers: {
_10
Method: "DELETE",
_10
Authorization: `Bearer ${ITTYBIT_API_KEY}`,
_10
},
_10
});

Endpoint

https://api.ittybit.com/media/:id

HTTP Method

DELETE

Description

Deletes a media item and all its sources, tracks, intelligence, and metadata.

Individual files can be deleted using the Files API.

NOTE: To avoid accidental data loss we retain the data and files for ~24 hours before permanently deleting it. If you need to restore an item within this period, please contact support.

response.json

_17
{
_17
"meta":{
_17
"id": "req_abcdefgh1234",
_17
"org_id": "org_abcdefgh1234",
_17
"project_id": "prj_abcdefgh1234",
_17
"method": "DELETE",
_17
"host": "https://api.ittybit.com",
_17
"path": "/media/med_abcdefgh1234",
_17
"version": "2024-08-21",
_17
"status": 200,
_17
"type": null
_17
},
_17
"data": null,
_17
"links": {
_17
"parent": "https://api.ittybit.com/media",
_17
}
_17
}