canonical: https://jentic.com/apis/melod.ie/melodie

# Melodie API

The Melodie API provides programmatic access to a royalty-free music catalogue licensed for use in video, podcast, advertising, and game projects. The 14 endpoints let you search tracks by genre, mood, instrument, and purpose, browse curated collections, surface trending content, and download licensed audio files. The catalogue is annotated with structured taxonomies for genre groups, moods, and intended usage, which makes the API well suited to creative tooling that needs to match music to scenes or campaigns.

## For AI agents

Search and download royalty-free music tracks from Melodie's catalogue, filtered by genre, mood, instrument, or purpose. Returns licensed audio files for video, podcast, and ad production.

## Scope

Does not handle music streaming, lyrics, or sound effects - use for royalty-free music catalogue search and licensed downloads only.

## Capabilities

- Search the catalogue by free-text query, genre, mood, instrument, and intended purpose across `/api/v1/tracks/search`
- Surface trending tracks in real time for content tooling that needs fresh music
- Browse curated collections for thematic projects such as travel, fitness, or corporate explainers
- Filter tracks by mood and genre group taxonomies to match audio to a scene or brand tone
- Download a licensed audio file for an approved track in MP3 or WAV form
- Retrieve track metadata including BPM, duration, instrument list, and licensed-use territories

## Use cases

### Video Editor Music Picker

Editorial and social-video tools embed Melodie search to give creators a royalty-free music picker scoped to their project. The `/api/v1/tracks/search` endpoint accepts mood, genre, and purpose filters in one request, returning a paged result the editor can audition without leaving the timeline. Integration takes a single afternoon because the API requires no authentication for catalogue browsing.

Example prompt: Call `/api/v1/tracks/search` with mood=upbeat, purpose=travel, max_duration=120, return the top 10 tracks with preview URLs.

### Podcast Background Music Selection

Podcast production platforms surface Melodie trending and collection endpoints so hosts can pick intro and bed music aligned with episode themes. Trending data refreshes daily, which keeps libraries from feeling stale, and curated collections provide pre-vetted music sets for genres like business, true crime, or comedy.

Example prompt: Fetch the 'business podcast' collection from `/api/v1/collections`, then return the five tracks with the longest available loop region.

### Generative Video Soundtrack Matching

AI video generation platforms call the Melodie taxonomy endpoints - moods, genres, instruments, purposes - to map a generated scene description to a structured music search. The taxonomy gives the LLM a fixed vocabulary to project natural-language scene mood onto, which produces more consistent music selection than free-text search alone.

Example prompt: Read the moods list from `/api/v1/tracks/moods`, map the scene description 'a tense chase through Tokyo at night' to mood=tense and genre=electronic, then run `/api/v1/tracks/search.`

### AI Agent Music Sourcing

An AI agent embedded in a creator tool can take a natural-language brief - 'find me three acoustic tracks under two minutes for a wedding montage' - and resolve it into a structured Melodie search. Through Jentic, the agent loads the search schema and the moods/instruments/purposes taxonomies in one session and chains the calls without writing custom client code.

Example prompt: Search Jentic for 'find royalty-free music', load `/api/v1/tracks/search`, execute with mood=romantic, instrument=acoustic-guitar, max_duration=120, return three results with download URLs.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/tracks/search` | Faceted search across the track catalogue |
| GET | `/api/v1/tracks/simplified_search` | Lightweight search endpoint with reduced response payload |
| GET | `/api/v1/tracks/trending` | List currently trending tracks |
| GET | `/api/v1/collections` | Browse curated collections |
| GET | `/api/v1/collections/{collection_safename}` | Get tracks in a specific collection |
| GET | `/api/v1/tracks/moods` | List available mood tags |
| GET | `/api/v1/tracks/genres` | List available genre tags |
| GET | `/api/v1/tracks/purposes` | List available usage purpose tags |

## Key resources

- **Search** — Free-text and faceted search across the catalogue with mood, genre, instrument, and purpose filters.
- **Collections** — Curated thematic groupings of tracks for use cases like travel, fitness, or corporate video.
- **Trending** — Daily-refreshed list of currently popular tracks in the catalogue.
- **Download** — Endpoints to retrieve the licensed audio file for an approved track.
- **Taxonomies** — Genres, genre groups, moods, instruments, and purposes - the controlled vocabularies used to filter searches.

## Why Jentic

- **Setup:** Wiring Melodie by hand means hand-coding each track search, collection, and taxonomy call against api.melod.ie and adding account credentials only where licensed downloads require them. Through Jentic you install once, import the Melodie API from the API Directory, store any download token once, and your agent calls it.
- **Permission scoping:** Melodie's search and taxonomy endpoints are public reads and the collection id travels in the path (`/collections/{collection_safename}`), so scope the agent to the read operations it needs, such as searching tracks or listing collections. You choose the operations it may call, so a licensed download is included only if you add it.
- **Credential handling:** Any Melodie account token for licensed download flows is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find royalty-free music for a video', and Jentic returns `/api/v1/tracks/search` with its full filter schema for mood, genre, instrument, purpose, and duration so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Epidemic Sound** — Larger royalty-free catalogue with a different licensing model
- **Soundstripe** — Subscription-based royalty-free music with similar mood/genre search
- **Freesound** — Community sound effects and field recordings under Creative Commons

## FAQ

### What authentication does the Melodie API use?

The OpenAPI spec declares no security scheme - catalogue browsing endpoints are open. Download endpoints typically require a licensed account; through Jentic any account credential is held in the encrypted vault and injected at request time.

### Can I filter tracks by mood and instrument together with the Melodie API?

Yes. `/api/v1/tracks/search` accepts mood, genre, instrument, and purpose filters in the same request, and you can preload the allowed values from `/api/v1/tracks/moods` and `/api/v1/tracks/instruments` to drive a UI.

### What are the rate limits for the Melodie API?

The OpenAPI spec does not declare quantitative rate limits. In practice catalogue search is generously rated for client-side use; download endpoints are gated by your licence tier. Watch for 429 responses and back off if seen.

### How do I find a track for a specific scene through Jentic?

Run `pip install jentic`, search for `find royalty-free music`, load the `/api/v1/tracks/search` operation, and execute with the desired mood, genre, and max_duration. Jentic returns the matched tracks with preview URLs.

### Does the Melodie API cover trending music?

Yes. The `/api/v1/tracks/trending` endpoint returns a daily-refreshed list of popular tracks in the catalogue, which is useful for keeping music libraries fresh in production tooling.

### Can I limit what my agent is allowed to do with the Melodie API?

Yes. Because Jentic One is self-hosted, you decide which Melodie operations your agent may call and your own rules govern access. You can allow only the public read endpoints it needs, such as `/api/v1/tracks/search`, the mood, genre, and purpose taxonomy lists, and `/api/v1/collections` for browsing curated sets. A licensed download operation is included only if you explicitly add it, and any download token stays with your instance rather than the agent's context.