Media API BETA

The Media API can be used to upload, download and delete media items such as audio files for use with other Nexmo APIs.

Media

The Media object contains information about the request and details of the media object.

Key

Description
id
string

A UUID representing the object.
original_file_name
string

The filename of the object as it was originally uploaded.
mime_type
string

The IETF MIME type of the file.
account_id
string

The ID of your Nexmo account. This is the same as your API key.
store_id
string

An internal identifier of how the file is stored.
max_downloads_allowed
integer

The maximum number of times the file may be downloaded.
times_downloaded
integer

The number of times the file has been downloaded.
etag
string

An identifier for the content. This will change if the content of the file has been changed (i.e. if you upload a new version of the file). For more information see Wikipedia: HTTP ETag
media_size
integer

The size of the file in bytes
time_created
string

A timestamp for the time that the file was created
time_last_updated
string

A timestamp for the time that the file was last modified
public
boolean

Whether the item is available for download without authentication.

Example Model

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "original_file_name": "test.wav",
  "mime_type": "audio/vnd.wave",
  "account_id": "abcd1234",
  "store_id": "s3",
  "max_downloads_allowed": 0,
  "times_downloaded": 1,
  "etag": "aaaaaaaabbbbccccdddd0123456789ab",
  "media_size": 1234567,
  "time_created": "2020-01-01T14:00:00.000Z",
  "time_last_updated": "2020-01-01T14:00:00.000Z",
  "public": false
}

Upload media

This endpoint is used to upload media files (usually audio) to the media service. Upon successful upload, you will get back a response with status 201 Created giving you a Location header pointing to the metadata for the media file.

The media file will be associated with both your account and the Application ID of the JWT you use. This enables you to separate media files out by application.

The binary of the file can be downloaded at /v3/media/:id.

POST


          https://api.nexmo.com/v3
          /media

Request body multipart/form-data

Key

Description

Example

Default
filedata
string (binary)

A URL to a file to upload.

Note: Can not be used in conjunction with url.

None

None
url
string (url)

A URL to a file to upload.

Note: Can not be used in conjunction with filedata.

https://example.com/audio.wav

None
filename
string (binary)

You can give a string here for replace the file name

my-file.wav

None

201 HTTP response

No content

List and search media items

Retrieve information about multiple media items with the ability to search and paginate.

GET


          https://api.nexmo.com/v3
          /media

Query Parameter

Key

Description

Example

Default
order
string

The order of search results.

Must be one of: assendingordescending

assending

descending
page_index
integer

Which page to retrieve in pagination

1

0
page_size
integer

How many items at most per page

50

20
start_time
string

Retrieve results created on or after this timestap.

2020-01-01T14:00:00.000Z

1 week ago
end_time
string

Retrieve results created on or before this timestap.

2020-01-01T14:00:00.000Z

None

200 HTTP response

{
  "page_size": 20,
  "page_index": 0,
  "_links": {
    "self": {
      "href": "/v3/media?page_size=20&account_id=abcd1234&order=descending"
    },
    "first": {
      "href": "/v3/media?page_size=20&account_id=abcd1234&order=descending"
    },
    "last": {
      "href": "/v3/media?page_size=20&account_id=abcd1234&order=descending"
    }
  },
  "count": 1,
  "_embedded": {
    "media": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "original_file_name": "test.wav",
        "mime_type": "audio/vnd.wave",
        "account_id": "abcd1234",
        "store_id": "s3",
        "max_downloads_allowed": 0,
        "times_downloaded": 1,
        "etag": "aaaaaaaabbbbccccdddd0123456789ab",
        "media_size": 1234567,
        "time_created": "2020-01-01T14:00:00.000Z",
        "time_last_updated": "2020-01-01T14:00:00.000Z",
        "public": false
      }
    ]
  }
}

Retrieve a media item

Retrieve information about a single media item

GET


          https://api.nexmo.com/v3
          /media/:id/info

200 HTTP response

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "original_file_name": "test.wav",
  "mime_type": "audio/vnd.wave",
  "account_id": "abcd1234",
  "store_id": "s3",
  "max_downloads_allowed": 0,
  "times_downloaded": 1,
  "etag": "aaaaaaaabbbbccccdddd0123456789ab",
  "media_size": 1234567,
  "time_created": "2020-01-01T14:00:00.000Z",
  "time_last_updated": "2020-01-01T14:00:00.000Z",
  "public": false
}

Update a media item

Update a previously created media item by ID.

PUT


          https://api.nexmo.com/v3
          /media/:id/info

Request body multipart/form-data

Key

Description

Example

Default
public
boolean

Whether the item is publicly available without authentication.

true

None
metadata_primary
string

A string containing metadata about the media file.

foo,bar

None
metadata_secondary
string

A string containing further metadata about the media file.

123

None
title
string

A string containing a title for the media file.

Very important recording

None
description
string

A description of the media file.

This is a very important recording. Do not delete.

None
mime_type
string

The MIME type of the media file.

audio/vnd.wave

None
max_downloads_allowed
integer

The maximum number of times the file may be downloaded. Unlimited when not provided.

100

None

204 HTTP response

No content

Delete a media item

Delete a previously created media item by ID.

DELETE


          https://api.nexmo.com/v3
          /media/:id/info

204 HTTP response

No content