Skip to main content
API docs by Redocly

Epidemic Sound API (0.1.17)

Download OpenAPI specification:Download

Base URL: https://api.epidemicsound.com

If you're using the old base URL (https://partner-content-api.epidemicsound.com), it will keep working for /v0 endpoints, but we encourage you to switch to the new subdomain. You can make the switch without additional changes to your integration.

Authentication

Endpoints for user authentication.

Request a partner token Deprecated

Request a Partner Token

Request Body schema: application/json

Token request

accessKeyId
required
string
accessKeySecret
required
string

Responses

Request samples

Content type
application/json
{
  • "accessKeyId": "string",
  • "accessKeySecret": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJwYXJ0bmVyIiwiaXNzIjoiRXBpZGVtaWMgU291bmQiLCJwYXJ0bmVySWQiOiJlcGlkZW1pY3NvdW5kIiwiZXhwIjoxNjIwMTA4OTg0fQ"
}

Request a user token Deprecated

Request a User Token. This endpoint requires a Partner Token for authentication.

Authorizations:
Partner_Content_API_PartnerAuth
Request Body schema: application/json

Token request

userId
required
string

End user id. UUID, numeric or matching ^[a-zA-Z0-9_-]+$

Responses

Request samples

Content type
application/json
{
  • "userId": "ee11cbb1-9052-340b-87aa-c0ca060c23ee"
}

Response samples

Content type
application/json
{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1c2VyVGllciI6ImJhc2VfdGllciIsImF1ZCI6ImVuZC11c2VyIiwiaXNzIjoiRXBpZGVtaWMgU291bmQiLCJwYXJ0bmVySWQiOiJlcGlkZW1pY3NvdW5kIiwiZXhwIjoxNjIwMTA5MDkyLCJ1c2VySWQiOiJ1c2VyX2lkIn0"
}

List collections

The collections endpoint returns playlists curated by our team of in-house experts.

We offer collections for any occasion: from holidays like "Día de Muertos" to content types like "Real Estate" or "Badass ads".

You can manage the order and which collections are part or your applications' free tier via the developer portal. As default, we return the collections included in your free tier first, followed by all collections in the Epidemic Sound library.

Collections have attributes like title and cover art. In the few cases where we do not have cover art for a collection we return a default image.

You can choose to return collections with or without tracks. The response will include a maximum of 20 tracks per collection. If a collection contains more than 20 tracks use endpoint '/collections/{collectionId}' to get all tracks.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
excludeField
string
Value: "tracks"

Add parameter if tracks should be excluded in the response

limit
integer <int32>

Max number of entries returned in the response, default 10 and max 20

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

Collection details

The collections endpoint allows you to list all the tracks in a specific collection.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
collectionId
required
string

Collection id

query Parameters
limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

Search autosuggest

The search suggestions endpoint allows your users to get autocomplete suggestions for Epidemic Sound music or external provider music search.

Returns:

  • value: The exact search term to pass to the /tracks/search endpoint.
  • title: Display text to show users in the autocomplete UI.
  • type - Indicates whether this is a search term of type text or external reference URI (e.g., Spotify track).

Usage: When a user selects a suggestion, use the 'value' field as the 'term' parameter when calling /tracks/search to get matching tracks.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
term
string

Term for search

Responses

Response samples

Content type
application/json
{
  • "suggestions": [
    ]
}

List moods

The moods endpoint allows your users to browse the music catalog based on moods like happy, epic or relaxing. Moods have cover art that you can show in your interface.

By specifying the "type" of moods you want to display, you can choose to show all moods in the Epidemic Sound library, only the moods that are featured on epidemicsound.com or only the moods that are available for your free tier tracks.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
sort
string
Default: "relevance"
Enum: "alphabetic" "relevance"

Sorting options. Available values: alphabetic, relevance

order
string
Default: "asc"
Enum: "asc" "desc"

Order options. Available values: asc, desc

type
string
Default: "all"
Enum: "all" "featured" "partner-tier"

Types to filter by:

  • all - all the objects in the Epidemic Sound library
  • partner-tier - objects available to the partner within their tier
  • featured - only objects featured and curated by Epidemic Sound
limit
integer <int32>

Max number of entries returned in the response, default 20 and max 20

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

Mood details

Get mood details

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
moodId
required
string

Mood id

query Parameters
expand
string
Value: "tracks"

Add parameter if tracks should be included in the response

limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

List genres

The genres endpoint allows your users to browse the music catalog based on genres like rock, hiphop or acoustic.

Genres are nested and both parent and child genres are returned in the response. Parent genres have cover art that you can show in your interface.

By specifying the "type" of genres you want to display, you can choose to show all genres in the Epidemic Sound library, only the genres that are featured on epidemicsound.com or only the genres that are available for your free tier tracks.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
sort
string
Default: "relevance"
Enum: "alphabetic" "relevance"

Sorting options. Available values: alphabetic, relevance

order
string
Default: "asc"
Enum: "asc" "desc"

Order options. Available values: asc, desc

type
string
Default: "all"
Enum: "all" "featured" "partner-tier"

Types to filter by:

  • all - all the objects in the Epidemic Sound library
  • partner-tier - objects available to the partner within their tier
  • featured - only objects featured and curated by Epidemic Sound
limit
integer <int32>

Max number of entries returned in the response, default 20 and max 20

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

Genre details

This endpoint gives you the parent and child relationships of a specific genre as well as all tracks that belong to it.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
genreId
required
string

Genre id

query Parameters
expand
string
Value: "tracks"

Add parameter if tracks should be included in the response

limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

Tracks

Endpoints to get track specific information.

List tracks based on mood, genre or BPM

The tracks endpoint allows you to list all tracks based on a specified mood, genre or BPM.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
genre
Array of strings

Id for genre

mood
Array of strings

Id for mood

bpmMin
integer <int32>

BPM Min

bpmMax
integer <int32>

BPM Max

vocalType
Array of strings
Items Enum: "LEAD" "PRESENCE" "NONE"

Filter by vocal classification: LEAD (sung lead vocals), PRESENCE (vocal chops/samples/ad-libs/textures) or NONE (instrumental). Repeat the parameter to pass multiple values, which are OR-combined.

filterBehaviour
string
Enum: "allOf" "anyOf"

Control how the API combines several values of the same filter, such as two moods or two genres.

  • allOf returns only tracks that match every value. This is the default.
  • anyOf returns tracks that match at least one value, which widens the result set.

The vocalType filter always combines its values with anyOf.

limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

Tracks metadata

The metadata endpoint returns metadata for a list of tracks.

Identify each track by either its track id or its International Standard Recording Code (ISRC), and mix both kinds of value in the same request. The response de-duplicates a track that you request by both its track id and its ISRC.

If a value matches no track, the response omits that track instead of returning an error.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
trackId
required
Array of strings

List of track identifiers. Each value is either a track id or an ISRC, such as SE5Q52401263. ISRC matching ignores case, dashes, and spaces.

Responses

Response samples

Content type
application/json
[]

List track parameters

Get a list of possible track query parameters

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "genres": [
    ],
  • "moods": [
    ]
}

Download track

The download endpoint allows you to download an MP3 file of the track.

We offer MP3 files in two qualities; normal (128kbps) and high (320kbps).

The high quality files can be used in content when needed, but normal quality is sufficient for most use cases.

The download links expire after 24 hours (normal quality) or 1 hour (high quality files). The expiration time is stated in the response.

All users can download the tracks that are part of the free tier. Only connected users with an active Epidemic Sound subscription can download tracks that are part of the premium library. If a user does not have access to download a track, you will get an error response. You can proactively mark premium tracks in your UI by using the track attribute isPreviewOnly (see track attributes).

Use expand=stems to also get download links for the track's stems (e.g. drums, bass, melody), in the same quality as the track. Which stems exist depends on the track; each stem type appears at most once, and stems is an empty list when the track has none. Identify stems by their type rather than their position in the list. Stem links expire at the same time as the track link. Downloading a track with its stems counts as a single download.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

query Parameters
format
string
Value: "mp3"

Track format

quality
string
Default: "normal"
Enum: "normal" "high"

Track quality, normal is used as the default if not specified

expand
string
Value: "stems"

Use stems to include download links for the track's stems in the response

Responses

Response samples

Content type
application/json
{}

Lyrics

Returns the lyrics for a track when available. The response contains a single lyrics field as a plain string with newline-separated lines.

Returns lyrics: null for instrumental tracks (hasVocals: false) and for vocal tracks whose lyrics have not been registered yet. A hasVocals: true value on the track response does not guarantee that lyrics are available, so always handle the null case before rendering.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "lyrics": "Verse 1\nLine one\nLine two\n\nChorus\n..."
}

Preview track using cookies

We recommend using HLS to allow users to play/preview a track. The main benefits of this compared to MP3 are smaller file transfers and alternate qualities, allowing the HLS client library to switch to a lower quality when necessary.

The audio is encoded using the AAC coding standard, which results in a smaller footprint for a similar quality compared to MP3. The primary manifest refers to two variant quality streams. HLS client libraries typically choose the optimal quality automatically, based on download speed.

The format consists of audio files split into smaller chunks and manifests that refer to these audio files. Since the format is made up of multiple files, access to these are controlled using cookies.

We provide an example app for iOS that plays HLS streams. Users do not need to connect their account or have an active Epidemic Sound subscription to play any track using HLS streaming. That allows your users to listen to all tracks before they connect their account.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

Responses

Response samples

Content type
application/json
{}

Similar tracks

The similar tracks endpoint allows developers to retrieve a list of tracks that are similar to a given reference track. This feature is designed to help users discover tracks that share similar characteristics, such as genre, mood, tempo, and more. This endpoint helps your users replace tracks that don't fit perfectly or discover multiple alternatives to a track they enjoy.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

query Parameters
offset
integer <int32>

Index of the entry track in the response

limit
any

Max number of entries returned in the response, default 50 and max 60

Responses

Response samples

Content type
application/json
{}

Similar track segment based on audio file

Returns a list of track sections that are matched to the provided audio file id.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
audioUploadId
required
string <uuid>

Reference to the uploaded audio file

start
required
integer <int32>

Start of the section in milliseconds

end
required
integer <int32>

End of the section in milliseconds

offset
integer <int32>

Index of the entry track in the response

limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

Responses

Response samples

Content type
application/json
{}

Similar track segment based on trackID

The similar segments endpoint allows developers to use part of a track as a reference to search for music segments in the Epidemic Sound catalog that sound similar.

The feature utilizes the Epidemic Audio Reference (EAR) technology to provide users with the ability to quickly find alternative segments of music.

Usage Scenarios:

  • Video Editing Templates: Replace default tracks in video templates with segments that fit better.
  • Quick Swaps: Swap out a segment of music in a video where the existing track doesn't quite match.
  • Creative Iteration: Easily experiment with different music segments to enhance your video's impact.
Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

query Parameters
start
required
integer <int32>

Start of the section in milliseconds

end
required
integer <int32>

End of the section in milliseconds

offset
integer <int32>

Index of the entry track in the response

limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

Responses

Response samples

Content type
application/json
{}

Preview track

We recommend using HLS to allow users to play/preview a track. The main benefits of this compared to MP3 are smaller file transfers and alternate qualities, allowing the HLS client library to switch to a lower quality when necessary.

The audio is encoded using the AAC coding standard, which results in a smaller footprint for a similar quality compared to MP3. The primary manifest refers to two variant quality streams. HLS client libraries typically choose the optimal quality automatically, based on download speed.

The format consists of audio files split into smaller chunks and manifests that refer to these audio files.

We provide an example app for iOS that plays HLS streams. Users do not need to connect their account or have an active Epidemic Sound subscription to play any track using HLS streaming. That allows your users to listen to all tracks before they connect their account.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

Responses

Response samples

Content type
application/json
{}

Popular segment

Powered by our 2 billion daily streams on YouTube, the popular segments endpoint uses machine learning to recommend the best time section.

You can use popular segments to start playing the track from the right millisecond, or recommend the right part of the track for shorter content.

The popular segments endpoint provides start and stop timestamps in milliseconds. The default duration is 30 seconds.

The endpoint accepts up to 5 different durations per request where each duration must be at least 5 seconds and at most 60 seconds.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

query Parameters
duration
Array of integers <int32> [ items <int32 > ]

The highlight duration in seconds

Responses

Response samples

Content type
application/json
{
  • "highlights": [
    ]
}

Tracks based on image

Upload an image from the user's video to get recommendations of tracks in the Epidemic Sound library that would work for the video. Use ImageID retrieved from the Upload Image endpoint to fetch the recommended tracks.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
imageId
required
string

Image id

query Parameters
offset
integer <int32>

Index of the entry track in the response

limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

genre
Array of strings

Id for genre

mood
Array of strings

Id for mood

filterBehaviour
string
Enum: "allOf" "anyOf"

Control how the API combines several values of the same filter, such as two moods or two genres.

  • allOf returns only tracks that match every value. This is the default.
  • anyOf returns tracks that match at least one value, which widens the result set.

The vocalType filter always combines its values with anyOf.

Responses

Response samples

Content type
application/json
{}

Sound effects

Endpoints to get sound effect specific information. These endpoints allow you to build a UI to browse and search for sound effects.

List sound-effect collections

Returns the sound-effect collections active for your application.

Sound-effect collections are managed via the developer portal: an admin imports an EMS playlist into a collection, and end users see only Active collections through this endpoint.

Every application has access to every sound effect, so there is no per-tier cap and no paid/free distinction. Up to 20 sound effects per collection are included by default; pass excludeField=soundEffects to omit them, or paginate the full set via /sound-effects/collections/{collectionId}.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
excludeField
string
Value: "soundEffects"

Pass soundEffects to omit sound-effect data from the response and return only collection metadata.

limit
integer <int32>

Max number of collections returned in the response, default 10 and max 20

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

Sound-effect collection details

Returns a single sound-effect collection along with a paginated set of its sound effects. Use limit and offset to page through the collection.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
collectionId
required
string

Collection id

query Parameters
limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

offset
integer <int32>

Index of the entry track in the response

Responses

Response samples

Content type
application/json
{}

List SFX categories

The sound effects categories endpoint allows you to get a list of all sound effects categories.

You can then browse the sound effects catalog based on categories like "Applause" or "Crowds".

Some sound effect categories have cover art that you can use in your interface. You can choose to display all categories, or choose type "featured" to only show the categories that are chosen by our curation team.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
query Parameters
type
string
Default: "all"
Enum: "all" "featured"

Category type

offset
integer <int32>

Index of the entry track in the response

limit
any

Max number of entries returned in the response, default 50

Responses

Response samples

Content type
application/json
{}

SFX category details

The category details endpoint contains info on the requested sound effects category.

The purpose of this endpoint is to be able to validate that an individual object exists in the API if it was cached by the client.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
categoryId
required
string <uuid>

Category id

Responses

Response samples

Content type
application/json
{}

List SFX by category

Use the sound effects details endpoint to display all sound effects for a given category.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
categoryId
required
string <uuid>

Category id

query Parameters
offset
integer <int32>

Index of the entry track in the response

limit
integer <int32>

Max number of entries returned in the response, default 50 and max 100

sort
string
Default: "newest"
Enum: "title" "newest" "length"

Sort

order
string
Default: "asc"
Enum: "asc" "desc"

Order

includeExplicit
boolean
Default: false

Whether to include sound effects tagged as explicit in the results. Defaults to false, meaning explicit content is excluded by default.

Responses

Response samples

Content type
application/json
{}

Download sound effect

The download endpoint allows you to download an MP3 file of the sound effect.

We offer MP3 files in two qualities; normal (128kbps) and high (320kbps).

The high quality files can be used in content when needed, but normal quality is sufficient for most use cases.

The download links expire after 24 hours (normal quality) or 1 hour (high quality files). The expiration time is stated in the response.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

query Parameters
format
string
Value: "mp3"

Track format

quality
string
Default: "normal"
Enum: "normal" "high"

Track quality, normal is used as the default if not specified

Responses

Response samples

Content type
application/json
{}

Reporting

These endpoints will allow you to report how tracks are used in your application.

Report usage in bulk

This endpoint should be used when you want to bulk report events to Epidemic Sound. We currently support the following events: trackPreviewed, trackDownloaded and tracksExported. Note that the limit for number of events per request is limited to 100. Also note that for events containing the field trackIds, the limit for number of trackIds per event is 50. Events may not contain a timestamp older than 7 days ago.

Authorizations:
Partner_Content_API_PartnerAuthPartner_Content_API_ApiKeyAuth
Request Body schema: application/json

Analytics report

required
Array of objects (Partner_Content_API_AnalyticsReportEvent)
Array
userId
string
timestamp
string <date-time>
userConnected
boolean or null
Partner_Content_API_TrackPreviewedEvent (object) or Partner_Content_API_TrackDownloadedEvent (object) or Partner_Content_API_TracksExportedEvent (object) (Partner_Content_API_AnalyticsEvent)

Responses

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "batchId": "12345",
  • "eventsCount": 10
}

Report usage

The usage endpoint lets you report when a user exports their content to social media or downloads the content file to their device. You can specify which platform (YouTube, Twitch, Instagram, Facebook, TikTok, Twitter or Other) they export the file to. Use the platform local if the user downloads the content to their device. This data is used for attribution and analytics purposes as well as to improve personalization.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
Request Body schema: application/json

Usage report

eventType
string
Value: "EXPORTED"
platform
required
string
Enum: "YOUTUBE" "TWITTER" "TWITCH" "FACEBOOK" "INSTAGRAM" "TIKTOK" "OTHER" "LOCAL"
trackIds
required
Array of strings
other
string or null

Responses

Request samples

Content type
application/json
{
  • "eventType": "EXPORTED",
  • "platform": "OTHER",
  • "trackIds": [
    ],
  • "other": "OptionalValueForWhenNoMatchingPlatformEnum"
}

Response samples

Content type
application/json
{
  • "message": "Ok"
}

Users

These endpoints allows your application to get user specific information such as liked sounds.

User details

Get user details of the authenticated user.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuth

Responses

Response samples

Content type
application/json
{
  • "userId": "ee11cbb1-9052-340b-87aa-c0ca060c23ee",
  • "esConnect": false,
  • "hasActiveSubscription": null,
  • "email": null
}

List users' liked tracks

The liked tracks endpoint lets you list the liked tracks of a connected user. Users can add new tracks to their list on epidemicsound.com or via the Epidemic Sound app, giving them a smooth cross-device experience.

Authorizations:
Partner_Content_API_EpidemicSoundConnectAuth
query Parameters
offset
integer <int32>

Offset for the pagination. For this endpoint the number of results is fixed at 25, so the offset needs to be evenly divisible by 25.

Responses

Response samples

Content type
application/json
{}

Assets

These endpoints allows your application to upload assets such as images or audio.

Get audio by checksum

Will return the audio id of an audio file uploaded by the partner, matched by checksum. Should be used to avoid duplicate uploads

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuthPartner_Content_API_PartnerAuth
path Parameters
checksum
required
string

File checksum

Responses

Response samples

Content type
application/json
{
  • "audioUploadId": "4f3f6b63-8521-3b2c-b238-5d00b47d2eaa",
  • "length": 10,
  • "expires": "2020-11-09T09:30:00Z"
}

Delete audio

Use the delete audio endpoint to delete an audio file.

Authorizations:
Partner_Content_API_PartnerAuthPartner_Content_API_ApiKeyAuth
path Parameters
audioIdOrChecksum
required
string

Audio upload id or checksum of audio file

Responses

Response samples

Content type
application/json
{
  • "audioFilesRemoved": [
    ]
}

Upload audio

Upload an audio file to get recommendations of similar tracks in the Epidemic Sound library. When you post the audio file to this endpoint, you will receive an AudioID in return. Use this AudioID in a request to the similar tracks endpoint to get track recommendations.

We currently support the formats: mp3, mpeg, ogg and vorbis. Maximum file size is 3.5MB. You can only upload music with the partner token, since we currently do not allow end users to use this feature.

Authorizations:
Partner_Content_API_PartnerAuthPartner_Content_API_ApiKeyAuth
Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "imageId": "78805a22-1a98-3e79-af3f-42d7c5bfd418",
  • "expirationDate": "2020-10-11T09:30:00Z"
}

Delete single image

Use the delete image endpoint to delete a single image uploaded by a user

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
imageId
required
string

Image id

Responses

Response samples

Content type
application/json
{
  • "message": "Bad request"
}

Delete all the uploaded images by the user

Deletes all images uploaded by the user

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid credentials"
}

Upload image

Upload an image from the user's video to get recommendations of tracks in the Epidemic Sound library that would work for the video. When you post the image to this endpoint, you will receive an ImageID in return. Use this ImageID in a request to the matching image endpoint to get track recommendations.

We currently support jpeg format and maximum file size is 2MB.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "imageId": "78805a22-1a98-3e79-af3f-42d7c5bfd418",
  • "expirationDate": "2020-10-11T09:30:00Z"
}

Beta

These endpoints are in beta.

Beats

The beats endpoint provides information about the timestamps of beats in a track. You can use this endpoint to simplify the process to cut the video in sync with the music.

Unlike BPM which is a single number for the entire track, beats can change dynamically across a music piece. This is particularly valuable for capturing variations in tempo, such as a slower intro, a build-up with faster beats, or changes in rhythm throughout the composition.

The response includes two types of metadata: time and value.

time represents the timestamp of the beat in seconds. value indicates the beat's position in a bar (or measure in the US), where 1 corresponds to the first beat (downbeat).

Examples:

Most pop songs have four beats in a bar. For example, if we looked at the beats data for Coolio's 1, 2, 3, 4 it would look something like: 1-2-3-4, 1-2-3-4

However, a waltz has three beats in a bar, and the data would look something like: 1-2-3, 1-2-3

Usage Scenarios:

  • Automatically cut a video in sync with the beat

  • Adding snap markers aligned with beat timestamps in the UI.

Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
trackId
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "beats": [
    ]
}

Start a track versions generation job

This endpoint allows you to start a job to generate edited versions of a track. The job will be processed asynchronously and you can check the status using the GET /tracks/versions/{jobId} endpoint. Note that the url expires in 24 hours.

Duration limits:

  • The duration must be between 1 second and 5 minutes.
  • Longer durations result in increased processing time, as latency scales with the desired duration.
Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
Request Body schema: application/json

Track edit request configuration

durationMs
required
integer <int32>
trackId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "durationMs": 0,
  • "trackId": "fcc44b18-493c-4040-a803-8be99a8f81ac"
}

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "results": [ ],
  • "message": "Job is still processing",
  • "jobId": "c2a89a00-967e-37fb-8d2a-34958c91e357"
}

Get track versions job status

This endpoint allows you to check the status of a track versions job. When the job is complete, it will return the URLs to the generated tracks.

Waveform Data:

  • By default, waveform data is excluded to reduce payload size
  • Use expand=waveform to include waveform data in the response
Authorizations:
Partner_Content_API_UserAuthPartner_Content_API_EpidemicSoundConnectAuthPartner_Content_API_ApiKeyAuth
path Parameters
jobId
required
any

The ID of the job to check

query Parameters
expand
any

Include additional data in response. Use 'waveform' to include waveform data.

Responses

Response samples

Content type
application/json
{}

Safelisting

Endpoints for managing safelisting licenses. Allows partners to create, list, update, and delete licenses for channels and videos on behalf of their end users.

Delete all licenses for an end user

Expires all active licenses for the specified end user within the workspace. Intended for end-user churn scenarios (e.g. when a user cancels their subscription). Returns 204 regardless of whether the user had any active licenses.

Authorizations:
Partner_Content_API_ApiKeyAuth
header Parameters
X-Partner-User-Id
required
any

The partner's end user identifier. Used to scope licenses per end user.

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid credentials"
}

List safelisting licenses

List safelisting licenses for the specified end user. Supports filtering by asset type, platform, and status, with pagination and sorting.

Authorizations:
Partner_Content_API_ApiKeyAuth
query Parameters
assetType
required
string
Enum: "channel" "video"

Filter by asset type

platform
string
Enum: "youtube" "instagram" "facebook" "twitch" "tiktok" "podcast" "website"

Filter by platform

status
string
Value: "active"

Filter by status. Currently only active licenses are returned.

sortBy
string
Default: "expiresAt"
Enum: "createdAt" "expiresAt"

Field to sort results by

sortOrder
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

page
integer <int32>
Default: 1

Page number (1-based)

pageSize
integer <int32>
Default: 25

Number of results per page

header Parameters
X-Partner-User-Id
required
any

The partner's end user identifier. Used to scope licenses per end user.

Responses

Response samples

Content type
application/json
{
  • "page": 1,
  • "pageSize": 25,
  • "totalItems": 1,
  • "data": [
    ]
}

Create a safelisting license

Create a new safelisting license for a channel or video. The X-Partner-User-Id header is required to scope the license to a specific end user.

Authorizations:
Partner_Content_API_ApiKeyAuth
header Parameters
X-Partner-User-Id
required
any

The partner's end user identifier. Used to scope licenses per end user.

Request Body schema: application/json
required

License creation request

required
object (Partner_Content_API_SafelistingAssetRequest)
expiresAt
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "createdAt": "2024-06-01T10:00:00Z",
  • "expiresAt": "2026-12-31T23:59:59Z",
  • "asset": {}
}

Delete a safelisting license

Expire a safelisting license by ID. The license is soft-deleted and will no longer appear in active license listings.

Authorizations:
Partner_Content_API_ApiKeyAuth
path Parameters
licenseId
required
any

License ID

header Parameters
X-Partner-User-Id
required
any

The partner's end user identifier. Used to scope licenses per end user.

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid credentials"
}

Get a safelisting license

Retrieve a single safelisting license by ID. Returns 404 if the license does not exist or does not belong to the specified end user.

Authorizations:
Partner_Content_API_ApiKeyAuth
path Parameters
licenseId
required
any

License ID

header Parameters
X-Partner-User-Id
required
any

The partner's end user identifier. Used to scope licenses per end user.

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "createdAt": "2024-06-01T10:00:00Z",
  • "expiresAt": "2026-12-31T23:59:59Z",
  • "asset": {}
}

Update a safelisting license

Update a safelisting license. Currently only the expiration date can be modified.

Authorizations:
Partner_Content_API_ApiKeyAuth
path Parameters
licenseId
required
any

License ID

header Parameters
X-Partner-User-Id
required
any

The partner's end user identifier. Used to scope licenses per end user.

Request Body schema: application/json
required

License update request

expiresAt
required
string

Responses

Request samples

Content type
application/json
{
  • "expiresAt": "2027-12-31T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "createdAt": "2024-06-01T10:00:00Z",
  • "expiresAt": "2027-12-31T23:59:59Z",
  • "asset": {}
}

Authentication

Send your API key as a bearer token in the Authorization header on every request:

Authorization: Bearer <API key>

Rate limiting

Applies to /v1 and later endpoints. /v0 endpoints work differently.

Each app has a daily request limit, which resets at midnight UTC. You can find your app's limit in the developer portal.

We also enforce a burst request limit on a one-second window. It allows about five times the average rate of your daily limit.

Responses include two rate limit headers, in the format of the IETF RateLimit header fields draft:

RateLimit-Policy: "burst";q=290;w=1, "daily";q=5000000;w=86400
RateLimit:        "burst";r=41;t=1, "daily";r=4913204;t=48213

RateLimit-Policy names your limits, with the quota (q) and the window in seconds (w) of each. It changes only when your limits do. RateLimit says what is left of each, as the remaining requests (r) and the seconds until that limit resets (t).

Note that in some rare cases, these headers may be missing, for instance if rate limiting temporarily fails, or on certain error responses.

A request over either limit returns a 429 response and a Retry-After header stating the number of seconds to wait before you try again. Read the RateLimit header to keep under your limits instead of waiting for the 429.

In some exceptional cases, or when documented specifically for an endpoint, responses other than 429 may include a Retry-After header. Always honor it when present.

Compression

Send Accept-Encoding: gzip to have the response body compressed. The response then carries Content-Encoding: gzip. Leave the header out to receive the body unencoded.

Errors

Applies to /v1 and later endpoints. /v0 endpoints work differently.

An error is answered with Content-Type: application/problem+json and a problem document:

  • type identifies the error, for example /problems/not-found. It is the member to branch on.
  • title explains it in English, for a developer to read.
  • errors, when present, lists the fields that failed validation.

Some error responses, such as a 503 or 504, may include a Retry-After header with the number of seconds to wait before you try again. Always honor it when present.

Nearly every response, including successful ones, carries an X-Correlation-Id header that identifies the request. Quote it when you report a problem to us.

Soundtracking

Automatic soundtracking operations

Create a soundtrack job

Score a video with library music in one call. The call does not carry the video. It answers 202 with a job and an upload URL: send the whole video to that URL in a single PUT. The upload starts the job. Then poll GET /v1/soundtracking/jobs/{jobId} until the status is COMPLETED or FAILED, no more often than every 5 seconds. Videos must be four minutes or shorter. The length is not known until the video arrives, so this call accepts a longer one and the job then fails with VIDEO_TOO_LONG. Scoring a video costs credits. This call answers 402 when the workspace cannot cover it. The credits are taken when the upload finishes, not here. Idempotency-Key is optional and the value is yours to choose. Send one when you retry this call: a retry without it creates a second job and leaves the first unused. Undeclared fields in the body are ignored. A misspelled field name is dropped without a warning and the request still returns a success, so check the names against this specification.

Authorizations:
public-api-gateway_ApiKeyAuth
header Parameters
Accept-Encoding
string <= 128 characters
Example: gzip

The content encodings the client accepts. Ask for gzip to have the response body compressed, or leave the header out to receive it unencoded.

Idempotency-Key
string [ 1 .. 255 ] characters
Example: 4f6d1b6e-2c8f-4a9a-9f3a-2b6f1c0d5e21

A key you choose that makes a create safe to retry. A second call carrying a key already used in your workspace returns what the first call created, instead of creating another one. Send one when you retry a call whose answer you never saw. The key identifies the request on its own: the body is not compared, so use a different key for different parameters.

Request Body schema: application/json
required

The video to score, and how to score it.

filename
required
string [ 1 .. 512 ] characters

Name of the video file. It is what the stored file is named after, so keep the extension.

contentType
required
string [ 1 .. 128 ] characters

Media type of the video, which has to be a video/* type. It is declared to storage when the upload is prepared, so the stored file carries it rather than whatever the upload request sends. The media type names the container, not the codec inside it, so it is not on its own a statement that we can read the video. That is settled when the bytes arrive, and a video we cannot decode fails afterwards with UNSUPPORTED.

sizeBytes
required
integer <int64> [ 1 .. 629145600 ]

Size of the video in bytes, at most 600 MB. It is declared to storage when the upload is prepared, so an upload that does not match it is refused as it happens rather than stored and rejected afterwards. A size over the limit is refused by this call, before any bytes move.

audioTypes
Array of strings (public-api-gateway_SoundtrackAudioType) non-empty unique
Items Value: "MUSIC"

What the run adds to the video. Omit it to score the video with music, which is the same as sending ["MUSIC"].

brief
string [ 1 .. 2000 ] characters

Creative direction for the run: mood, genre, references. It guides the whole video rather than one section. Omit it to let the run decide from the video alone. The brief is a prompt, not a filter. It cannot guarantee a specific piece of music.

outputFormat
string (public-api-gateway_SoundtrackOutputFormat)
Enum: "MP4" "MP3" "WAV"

What you receive. MP4 is the video you uploaded with the soundtrack on it. MP3 and WAV are the mixed audio on its own, for cutting the video yourself.

sourceAudio
string (public-api-gateway_SoundtrackSourceAudio)
Enum: "MUTED" "UNMUTED"

What happens to the audio already on the video you upload. MUTED discards it, which suits footage with no dialog worth keeping. UNMUTED keeps it and mixes the soundtrack underneath at a fixed level.

Responses

Request samples

Content type
application/json
{
  • "filename": "interview-final.mp4",
  • "contentType": "video/mp4",
  • "sizeBytes": 52428800,
  • "audioTypes": [
    ],
  • "brief": "Warm indie folk, builds towards the end",
  • "outputFormat": "MP4",
  • "sourceAudio": "MUTED"
}

Response samples

Content type
application/json
{}

Get a soundtrack job

Get the current state of one soundtrack job. The result is 404 if the job does not exist, or if it belongs to a different workspace. Poll no more often than every 5 seconds. The URL in result.output is signed and expires. Polling a completed job returns a fresh one.

Authorizations:
public-api-gateway_ApiKeyAuth
path Parameters
jobId
required
string <uuid> (public-api-gateway_SoundtrackJobId)
Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier of the soundtrack job.

header Parameters
Accept-Encoding
string <= 128 characters
Example: gzip

The content encodings the client accepts. Ask for gzip to have the response body compressed, or leave the header out to receive it unencoded.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "FAILED",
  • "createdAt": "2026-09-22T12:30:00Z",
  • "updatedAt": "2026-09-22T12:34:00Z",
  • "brief": "Warm indie folk, builds towards the end",
  • "audioTypes": [
    ],
  • "outputFormat": "MP4",
  • "sourceAudio": "MUTED",
  • "error": {
    }
}