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.

Download OpenAPI 3 Definition

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