soundverse Trace
Use Cases
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
POST/trace/v3/comprehensive2Comprehensive – Deep
POST/trace/v3/coveris this a cover?
POST/trace/v3/remixis this a remix?
POST/trace/v3/genredo these songs share a style?
POST/trace/v3/lyricsare the lyrics reused?
POST/trace/v3/melodyis the melody reused?
POST/trace/v3/samplewas part of the recording sampled?
POST/trace/v3/timbredoes the voice and tone match?
Each returns 201 with a job_id. Poll it as described in Results & Billing; each layer the use case compares appears as its own block in the results.
What each use case compares
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| comprehensive2 | anything similar? | No | — | Layers: track, section, motif, stem. Instruments: vocals, bass, drums, other. Text: lyrics, translation, insights. |
| cover | a cover? | No | — | Layers: track, section, motif, stem. Instruments: vocals. Text: lyrics, translation. |
| remix | a remix? | No | — | Layers: section, motif, stem. Instruments: vocals, bass, drums, other. Text: lyrics. |
| genre | same style? | No | — | Layers: track, stem. Instruments: vocals, bass, drums, other. Text: insights. |
| lyrics | lyrics reused? | No | — | Layers: section, stem. Instruments: vocals. Text: lyrics, translation. |
| melody | melody reused? | No | — | Layers: section, motif, stem. Instruments: vocals, other. No text signals. |
| sample | recording sampled? | No | — | Layers: section, motif, stem. Instruments: vocals, bass, drums, other. No text signals. |
| timbre | voice and tone? | No | — | Layers: track, stem. Instruments: vocals. Text: 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 a 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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| comprehensive2 | depth | No | — | ["track", "section", "motif", "stem", "lyrics", "translation", "insights"] |
| cover | depth | No | — | ["track", "section", "motif", "stem", "lyrics", "translation"] |
| remix | depth | No | — | ["section", "motif", "stem", "lyrics"] |
| genre | depth | No | — | ["track", "stem", "insights"] |
| lyrics | depth | No | — | ["section", "stem", "lyrics", "translation"] |
| melody | depth | No | — | ["section", "motif", "stem"] |
| sample | depth | No | — | ["section", "motif", "stem"] |
| timbre | depth | No | — | ["track", "stem", "insights"] |
Check readiness with dataset tracks before searching. A search against a dataset that lacks a required layer finishes as failed, and you are not charged.
Request fields
The same fields for every use case:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| search_type | "1:1" | "1:n" | "m:n" | Yes | — | The search shape. |
| query_file_id | string | No | — | Required for 1:1 and 1:n. The file_id of the song you are checking. |
| candidate_file_id | string | No | — | Required for 1:1. The file_id of the song to compare against. |
| candidate_dataset_name | string | No | — | Required for 1:n and m:n. The dataset to search. |
| query_dataset_name | string | No | — | Required for m:n. The dataset whose songs are the queries. |
| limit | integer | No | all matches | Maximum matches returned per query song. |
| budget_tokens | integer | No | no cap | Optional cap on what this job may cost. See Results & Billing. |
| query_url / candidate_url | string | No | — | Legacy alternatives to the file IDs: blob_name values from POST /trace/v3/upload. |
The use case decides the layers
Use-case searches ignore depth, stem_types, lyrics, translation and audio_to_text. To choose your own layers, use a custom search. Use cases with text signals need file_id inputs.
Example
curl -X POST https://apiv2.soundverse.ai/trace/v3/cover \
-H "Authorization: Bearer sksoundverse_..." \
-H "Content-Type: application/json" \
-d '{
"search_type": "1:n",
"query_file_id": "018f0000-0000-7000-8000-000000000003",
"candidate_dataset_name": "reference-catalog"
}'201 Created
{"job_id": "018f0000-0000-7000-8000-0000000000a3", "status": "queued"}To run a different use case, change only the path, for example /trace/v3/melody.
How matches are ordered
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 one particular signal, read that layer’s block rather than the overall order.