Search by prompt

Search the catalog with a natural-language prompt and get back ranked tracks with highlight regions for each result. Same input as by-text, different upstream — the prompt path returns per-track highlights: [{offset, duration}] so you can surface the most relevant section of each match (great for previews, in/out points, auto-cropping clips).

GET/api/v4/search/ai/by-prompt/

This is the endpoint the Slipstream MCP search_tracks tool uses under the hood. If you’re seeing highlight fragments in MCP results and not in your own integration, switch from by-text to by-prompt.

Query parameters

Parameter	Required	Default	Description
`text`	Yes	—	The natural-language prompt.
`highlights`	No	`false`	Set to `true` to include `highlights: [{offset, duration}]` on each result.
`time_offset`	No	`0`	Audio offset in seconds for the highlight analysis window.
`time_limit`	No	—	Audio duration limit in seconds (1–60) for the highlight analysis window.
`bpm_range`	No	`5`	BPM tolerance when matching by tempo.
`limit`, `offset`	No	—	Pagination.
Any filter parameter	No	—	Narrow results by genre, mood, BPM, etc.

Example request

curl "https://api.slipstreammusic.com/api/v4/search/ai/by-prompt/?text=upbeat%20indie%20pop%20for%20a%20commercial&highlights=true&limit=5" \
  -H "Authorization: Bearer $PARTNER_API_KEY"

Example response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "0328895e-af3f-4248-9173-69fed8ab25f5",
      "name": "Tonight We Dance",
      "artist": { "name": "Swami G", "slug": "swami-g" },
      "length": 87,
      "tempo": 106,
      "is_explicit": false,
      "is_free": true,
      "audio_url": "/api/v4/stream/0328895e-af3f-4248-9173-69fed8ab25f5/?type=track",
      "genre_name": "Rock",
      "subgenre_name": "Indie Rock",
      "mood_name": "Uplifting",
      "secondary_mood_name": "Uplifting",
      "vocals": "instrumental",
      "has_stems": true,
      "cover": "https://...",
      "release_date": "2025-09-12",
      "short_url": "https://slipstreammusic.com/t/...",
      "restricted": false,
      "highlights": [
        { "offset": 2.048, "duration": 15 },
        { "offset": 47.616, "duration": 38.912 }
      ]
    }
  ],
  "did_you_mean": null,
  "playlist_search": { "ids": [] }
}

See The Track object for the full field list. The highlights array is empty when highlights=true was not passed (or when AIMS couldn’t compute regions for that match).

Highlight regions

Each entry in highlights describes a contiguous region of the track:

Field	Description
`offset`	Start of the region, in seconds from the beginning of the track.
`duration`	Length of the region, in seconds.

Use these to drive automatic in/out points, preview clips, or thumbnail audio. The first entry is typically the strongest hook; subsequent entries are secondary regions of interest.

When to use `by-prompt` vs `by-text`

	`by-text`	`by-prompt`
Input	Natural-language query	Natural-language prompt
Returns highlights	No	Yes (with `highlights=true`)
Best for	Lightweight catalog browsing	Editor/preview flows that need clip regions

If you don’t need highlights, by-text is cheaper. For anything where the user picks a track and you want to surface the best section, use by-prompt.

Search by text Search by URL