Supe Search

Supe is Soundstripe's AI music supervisor. Describe the music you need, point us at the visual material if you have it, and Supe returns matching songs from the catalog with full metadata, signed audio URLs, and stems.

Unlike traditional filter-based search, Supe understands conversational descriptions of your project, mood, and creative vision. Search for upbeat indie rock for a travel vlog, attach a shot list to ground the result in your scene, or upload the visuals themselves and let Supe score directly against the imagery.

📘
Request access
Supe Search is available to enterprise partners and requires the Supe add-on enabled on your account. To get started, contact our team at soundstripe.com/enterprise or reach out to your account manager.

How it works

Supe Search is asynchronous. You submit a request with a callback URL and Supe delivers the results via webhook when the search completes.

(Optional) Upload reference assets by sending images or video to POST /v1/supe/assets. Each upload returns an asset ID you can reference from a search.
Submit a search by sending a POST request to /v1/supe/search with any combination of a natural language query, scene context, and uploaded asset_ids, plus a callback_url.
Receive a search ID in the response. If the same request was already answered recently, you get the full results immediately (200). Otherwise, you get a search ID with status: "processing" (202).
Receive results via webhook when the search completes. The webhook payload contains the matched songs with full metadata, signed audio URLs, and signed stem bundles.
Retrieve results later using GET /v1/supe/search/{search_id} if you need to fetch the results again after the webhook was delivered.

Inputs are flexible

A search must include at least one of query, context, or asset_ids. Combine them freely:

Text-only search: a natural language query, optionally paired with context for scene direction.
Visual search: upload up to 10 images and 1 video, reference them via asset_ids, and (optionally) layer text on top.
Context-grounded search: describe the scene in context while leaving query blank. Context-only requests must contain at least 12 characters of substantive direction so that trivial values like music are rejected.

Image and video search are enabled per account. Contact your account manager if you need to add visual search to your plan.

Caching

Equivalent searches are cached for 24 hours per API key. An equivalent request (same query, context, and asset_ids after Unicode normalization) returns the cached result synchronously as a 200 response and no webhook is sent. Song metadata, signed audio URLs, and stem URLs are always loaded fresh on cache hits, so URLs in a cached response are never stale.

If you submit a second equivalent request while the first is still processing, the response is a 202 echoing the existing search's ID and no duplicate work is enqueued. The webhook is delivered only to the first request's callback_url.

Authentication

Supe Search uses the same token authentication as the rest of the API:

-H "Authorization: Token APIKEY"

Notes

The callback_url must be HTTPS. HTTP URLs, private IP addresses (10.x, 192.168.x, 127.x), and cloud metadata endpoints (169.254.x) are rejected.
All signed URLs in a response (audio files and stems) expire 7 days after the response is generated. Fetch a fresh response via GET /v1/supe/search/{search_id} when a URL is approaching expiry.
The Supe Search endpoint shares the standard enterprise API rate limit of 25 requests per second per API key.

Questions or want to integrate?

Reach out to your Soundstripe account manager or contact our enterprise team at soundstripe.com/enterprise to request access, ask about pricing, or scope an integration.