Use-Case Search

🚀 apiv2 is live!

Trace is served from apiv2.soundverse.ai. Create your API key and manage billing at platform.soundverse.ai.

Each use case is a ready-made search for one question. Soundverse decides which layers, instruments and text signals it compares, so you only choose the songs. Every use case supports 1:1, 1:n and m:n.

Endpoints

/trace/v3/comprehensive2 (Comprehensive – Deep)
/trace/v3/cover
/trace/v3/remix
/trace/v3/genre
/trace/v3/lyrics
/trace/v3/melody
/trace/v3/sample
/trace/v3/timbre (Voice timbre)

What Each Use Case Compares

Use case	Ask it	Layers	Instruments	Text signals
`comprehensive2`	”Is this song similar in any way?”	`track`, `section`, `motif`, `stem`	vocals, bass, drums, other	lyrics, translation, insights
`cover`	”Is this a cover of that song?”	`track`, `section`, `motif`, `stem`	vocals	lyrics, translation
`remix`	”Is this a remix of that song?”	`section`, `motif`, `stem`	vocals, bass, drums, other	lyrics
`genre`	”Do these songs share a style?”	`track`, `stem`	vocals, bass, drums, other	insights
`lyrics`	”Are the lyrics reused?”	`section`, `stem`	vocals	lyrics, translation
`melody`	”Is the melody reused?”	`section`, `motif`, `stem`	vocals, other	none
`sample`	”Was part of the recording sampled?”	`section`, `motif`, `stem`	vocals, bass, drums, other	none
`timbre`	”Does the voice and tone match?”	`track`, `stem`	vocals	insights

The layers behind each use case are maintained by Soundverse and may be refined over time. If you need a fixed, explicit set of layers, use Custom Search.

Prepare Your Datasets

For 1:n and m:n, ingest the datasets with every depth the use case needs. A 1:1 search needs no ingestion.

Use case	Ingest with `depth`
`comprehensive2`	`["track", "section", "motif", "stem", "lyrics", "translation", "insights"]`
`cover`	`["track", "section", "motif", "stem", "lyrics", "translation"]`
`remix`	`["section", "motif", "stem", "lyrics"]`
`genre`	`["track", "stem", "insights"]`
`lyrics`	`["section", "stem", "lyrics", "translation"]`
`melody`	`["section", "motif", "stem"]`
`sample`	`["section", "motif", "stem"]`
`timbre`	`["track", "stem", "insights"]`

Check readiness with GET /trace/v3/dataset/{dataset_id}/tracks before searching. A search against a dataset that lacks a required layer finishes as failed, and you are not charged.

Request Body Fields

The same fields for every use case:

Field	Type	Required	Description
`search_type`	string	✅	`"1:1"`, `"1:n"` or `"m:n"`
`query_file_id`	string	1:1, 1:n	`file_id` of the song you are checking
`candidate_file_id`	string	1:1	`file_id` of the song to compare against
`candidate_dataset_name`	string	1:n, m:n	Name of the dataset to search
`query_dataset_name`	string	m:n	Name of the dataset whose songs are the queries
`limit`	integer		Maximum number of matches returned per query song
`budget_tokens`	integer		Optional cap on what this job may cost. See Errors & Billing
`query_url`, `candidate_url`	string		Legacy alternatives to the file IDs: `blob_name` values from `/trace/v3/upload`

Use-case searches ignore depth, stem_types, lyrics, translation and audio_to_text. The use case decides them. To choose your own, use Custom Search.

Use cases with text signals (lyrics, translation, insights) need file_id inputs. Trace looks up each song’s lyrics and tags through its file.

Request Example

curl -X POST "https://apiv2.soundverse.ai/trace/v3/cover" \
  -H "Authorization: Bearer sksoundverse_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "search_type": "1:n",
    "query_file_id": "0190a1b2-0003-7000-8000-00000000a003",
    "candidate_dataset_name": "reference-catalog"
  }'

import requests

resp = requests.post(
    "https://apiv2.soundverse.ai/trace/v3/cover",
    headers={"Authorization": "Bearer sksoundverse_your_api_key"},
    json={
        "search_type": "1:n",
        "query_file_id": "0190a1b2-0003-7000-8000-00000000a003",
        "candidate_dataset_name": "reference-catalog",
    },
)
job_id = resp.json()["job_id"]

To run a different use case, change only the path, for example /trace/v3/melody.

Response

Status 201 Created

{
  "job_id": "0190a1c0-4444-7000-8000-000000000104",
  "status": "queued"
}

Poll GET /trace/v3/jobs/{job_id} for the results. Each layer the use case compares appears as its own block, as described in Multiple layers.

Matches are ranked by the first available layer in this order: track, light_stem, stem, section, stem_section, motif. Use cases that include track therefore rank by the full mix. To compare songs on a specific signal, read that layer’s block rather than the overall order.

Errors

Validation errors return 422 and are the same as for Custom Search. For authentication, balance and rate-limit errors, see Errors & Billing.

Get Started

Frequently Asked Questions

Creating with Soundverse

Exploring Soundverse

Account Management

Enterprise Platform

API Documentation

Use-Case Search

🚀 apiv2 is live!

Use-Case Search

Endpoints

What Each Use Case Compares

Prepare Your Datasets

Request Body Fields

Request Example

Response

Errors

🚀 apiv2 is live!

​Use-Case Search

​Endpoints

​What Each Use Case Compares

​Prepare Your Datasets

​Request Body Fields

​Request Example

​Response

​Errors

Use-Case Search

Endpoints

What Each Use Case Compares

Prepare Your Datasets

Request Body Fields

Request Example

Response

Errors