Media

Introduction

endpoints


_10# Media
_10GET https://api.ittybit.com/media
_10POST https://api.ittybit.com/media
_10
_10# Media Item
_10GET https://api.ittybit.com/media/:id
_10PATCH https://api.ittybit.com/media/:id
_10DELETE https://api.ittybit.com/media/:id

Media describes the original assets in your Project.

Media can be uploaded or ingested in a range of formats and can have a kind of image, video, or audio.

A Media Item can contain a number of Sources which describe the different variants of the media that have been created and Intelligence Items which describe rich data that has been extracted from the media.

Additionally Media with a kind of video may have one or more Tracks, which provide additional metadata (like subtitles) to Players.

Example A

A Media Item with a kind of image might have one Source with a format of webp and another with a format of jpeg.

Example B

A Media Item with a kind of video might have one Source with a height of 1080px, one Source with a height of 480px, and another 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, one Source with a format of jpeg, one Intelligence with a kind of speech, another Intelligence with a kind of objects, and a Track with a kind of subtitles.

Endpoints

List Media

request.js

request.sh


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

Returns a list of all media.

Endpoint

GET /media

response.json


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

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.
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.
status string

The status of the media to return. Possible values are active, processing, waiting.

Create Media

request.js

request.sh


_17const BASE_URL = "https://api.ittybit.com";
_17
_17const response = await fetch(`${BASE_URL}/media`, {
_17  headers: {
_17    Method: "POST",
_17    Authorization: `Bearer ${env.ITTYBIT_API_KEY}`,
_17    "Content-Type": "application/json",
_17    body: JSON.stringify({
_17      url: "https://yourbucket.s3.amazonaws.com/your-file.mp4?signature=1234567890&expires=1234567890"
_17      metadata: {
_17        filename: "your-file.mp4",
_17        user_id: 123,
_17        source: "YourApp/iOS",
_17      },
_17    }),
_17  },
_17});

Creates a new media item by ingesting a file passed in via the url prop.

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

Endpoint

POST /media

response.json


_41{
_41  "meta":{
_41    "id": "req_abcdefgh1234",,
_41    "method": "POST",
_41    "url": "/media",
_41    "version": "2024-03-21",
_41    "status": 200,
_41    "org_id": "org_abcdefgh1234",
_41    "project_id": "prj_abcdefgh5678",
_41    "live_mode": false,
_41    "type": "object"
_41  },
_41  "data": {
_41    "id": "med_abcdefgh5678",
_41    "object": "media",
_41    "kind": "video",
_41    "width": 1920,
_41    "height": 1080,
_41    "duration": 60.0,
_41    "fps": 30.0,
_41    "filesize": 12345678,
_41    "sources": [
_41      // ... Source object
_41      // https://ittybit.com/docs/api/sources
_41    ],
_41    "tracks": [],
_41    "intelligence": [],
_41    "metadata": {
_41      "filename": "your-file.mp4",
_41      "user_id": 123,
_41      "source": "YourApp/iOS",
_41    },
_41    "status": "active",
_41    "created": "2024-03-30T15:00:00Z",
_41    "updated": "2024-03-30T15:00:00Z",
_41  },
_41  "links": {
_41    "self": "/media/med_abcdefgh5678",
_41    "parent": "/media",
_41  }
_41}

Body Parameters

url string

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.
alias string

A unique alias for the media. This will be used to generate the media URL. It should be unique to your project. It can contain letters, numbers, and hyphens. If not provided, we will use the default URL in the format /:media_id/original.
metadata object

A set of key-value pairs to store with the media. This can be used to store any additional information you need to associate with the media. For example, you might want to store the original filename, the user who uploaded the media, or any other data that is relevant to your project. Values can be a string, integer, number, boolean, or null. Nested objects are not supported – if you have an interesting use case for this, please let us know about it.

View Media

request.js

request.sh


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

Returns the details for a single media item.

Endpoint

GET /media/:id

response.json


_47{
_47  "meta":{
_47    "id": "req_abcdefgh1234",,
_47    "method": "GET",
_47    "url": "/media/med_abcdefgh1234",
_47    "version": "2024-03-21",
_47    "status": 200,
_47    "org_id": "org_abcdefgh1234",
_47    "project_id": "prj_abcdefgh1234",
_47    "live_mode": false,
_47    "type": "object"
_47  },
_47  "data": {
_47    "id": "med_abcdefgh1234",
_47    "object": "media",
_47    "kind": "video",
_47    "width": 1920,
_47    "height": 1080,
_47    "duration": 60,
_47    "fps": 30,
_47    "filesize": 12345678,
_47    "sources": [
_47      // ... Source object
_47      // https://ittybit.com/docs/api/sources
_47    ],
_47    "tracks": [
_47      // ... Track object
_47      // https://ittybit.com/docs/api/tracks
_47    ],
_47    "intelligence": [
_47      // ... Intelligence object
_47      // https://ittybit.com/docs/api/intelligence
_47    ],
_47    "metadata": {
_47      "filename": "your-file.mp4",
_47      "user_id": 123,
_47      "source": "YourApp/iOS",
_47    },
_47    "status": "active",
_47    "created": "2024-03-30T13:00:00Z",
_47    "updated": "2024-03-30T14:00:00Z",
_47  },
_47  "links": {
_47    "self": "/media/med_abcdefgh1234",
_47    "parent": "/media",
_47  }
_47}

Response Parameters

id string

Unique identifier for the media item.
kind string

The kind of media. Possible values are image, video, audio.
width integer

The width of the original asset in pixels.
height integer

The height of the original asset in pixels.
duration number

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

The frames per second of the original asset (for video).
filesize integer

The size of the original asset in bytes.
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.
intelligence array

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

A JSON object containing any custom metadata you have attached to the media item. Values can be a string, integer, float, boolean, or null. Nested objects are not supported – if you have an interesting use case for this, please let us know about it.
status string

The status of the media item. Possible values are active, processing, waiting.
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

request.js

request.sh


_17const BASE_URL = "https://api.ittybit.com";
_17
_17const response = await fetch(`${BASE_URL}/media/med_abcdefgh1234`, {
_17  headers: {
_17    Method: "PATCH",
_17    Authorization: `Bearer ${env.ITTYBIT_API_KEY}`,
_17    "Content-Type": "application/json",
_17    body: JSON.stringify({
_17      metadata: {
_17        "filename": "your-file.mp4",
_17        "user_id": 123,
_17        "source": "YourApp/iOS",
_17        "new_value": "New value"
_17      }
_17    }),
_17  },
_17});

Updates a media item's metadata.

Endpoint

PATCH /media/:id

response.json


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

Body Parameters

metadata object

The new metadata to attach to the media item. This will fully replace the existing metadata, so to retain values you should include them in the new object. To remove a value you can exclude it from the new object. To remove all metadata, you can pass an empty object: {}.

Delete Media

request.js

request.sh


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

Deletes a media item.

NOTE: This action will delete the media AND all its sources, intelligence, and metadata. To avoid accidental data loss we will 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.

Endpoint

DELETE /media/:id

response.json


_20{
_20  "meta":{
_20    "id": "req_abcdefgh1234",,
_20    "method": "DELETE",
_20    "url": "/media/med_abcdefgh1234",
_20    "version": "2024-03-21",
_20    "status": 200,
_20    "org_id": "org_abcdefgh1234",
_20    "type": "object"
_20  },
_20  "data": {
_20    "id": "med_abcdefgh1234",
_20    "status": "deleted",
_20    "created": "2024-03-30T13:00:00Z",
_20    "updated": "2024-03-30T16:00:00Z",
_20  },
_20  "links": {
_20    "parent": "/media",
_20  }
_20}