curl --request POST \
  --url https://cue.vibeset.ai/v1/match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "video_id": "69e5a58e73370adad5a10dc9",
  "top_k": 5
}
'

{
  "video_id": "69e5a58e73370adad5a10dc9",
  "lane": {
    "title": "Your shortlist",
    "reasoning": "Driving but unhurried — it carries the cuts without fighting the voice.",
    "matches": [
      {
        "track_id": "14792",
        "audio_id": "60184",
        "soundstripe_song_id": "14792",
        "soundstripe_audio_file_id": "60184",
        "score": 1,
        "bpm": 120,
        "instrumental": true,
        "duration_seconds": 164.01
      },
      {
        "track_id": "14857",
        "audio_id": "60251",
        "soundstripe_song_id": "14857",
        "soundstripe_audio_file_id": "60251",
        "score": 0.89,
        "bpm": 116,
        "instrumental": false,
        "duration_seconds": 235.38
      }
    ]
  }
}

{
  "video_id": "<string>",
  "job_id": "<string>",
  "status": "processing",
  "poll": "/v1/match/jobs/run_9f2c",
  "next": "<string>"
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

Match

Match music to a video

Pass a video_id for a shortlist. This answers three ways and they carry different bodies:

200: the video’s analysis is cached for your account’s engine. The lane is inline.
202 with a job_id: the analysis is not cached, so the match runs as a job. Poll GET /v1/match/jobs/{job_id}. A video that has just turned ready normally takes this branch: ingest flips the row to ready before the engine analysis is persisted.
202 with no job_id: the video is still ingesting. Poll GET /v1/videos/{id} until ready, then call this endpoint again.

Passing a video_url instead of a video_id starts an ingest and returns that third shape. There is no job_id on that path.

POST

match

curl --request POST \
  --url https://cue.vibeset.ai/v1/match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "video_id": "69e5a58e73370adad5a10dc9",
  "top_k": 5
}
'

{
  "video_id": "69e5a58e73370adad5a10dc9",
  "lane": {
    "title": "Your shortlist",
    "reasoning": "Driving but unhurried — it carries the cuts without fighting the voice.",
    "matches": [
      {
        "track_id": "14792",
        "audio_id": "60184",
        "soundstripe_song_id": "14792",
        "soundstripe_audio_file_id": "60184",
        "score": 1,
        "bpm": 120,
        "instrumental": true,
        "duration_seconds": 164.01
      },
      {
        "track_id": "14857",
        "audio_id": "60251",
        "soundstripe_song_id": "14857",
        "soundstripe_audio_file_id": "60251",
        "score": 0.89,
        "bpm": 116,
        "instrumental": false,
        "duration_seconds": 235.38
      }
    ]
  }
}

{
  "video_id": "<string>",
  "job_id": "<string>",
  "status": "processing",
  "poll": "/v1/match/jobs/run_9f2c",
  "next": "<string>"
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Provide either 'video_id' or 'video_url'.",
    "request_id": "a1b2c3d4e5f6"
  }
}

Authorizations

Authorization

string

header

required

Your API key as a Bearer token, e.g. Authorization: Bearer vbsk_live_...

Headers

Idempotency-Key

string

Suppresses a DUPLICATE BILLING ROW for a retry of this exact request. It does not return the earlier response and does not stop the match re-running. Use a new key per distinct request. A key pinned across different requests silently suppresses billing for all of them.

Query Parameters

expand

enum<string>

Set to full for the full track object plus the lane's candidate pool.

Available options:

full

Body

application/json

Provide either video_id or video_url.

video_id

string

An already-ingested video.

Maximum string length: 128

video_url

string

A public https video URL. Ingested first, so the response is a 202 pointing at the video, with no job_id. Share links that redirect (Google Drive, Dropbox, S3, most CDNs) work, and we follow the redirect to the file.

Maximum string length: 2048

top_k

integer

default:20

MAXIMUM number of matches to return. The lane is planned as a shortlist of up to 10, so a larger value returns everything there is rather than more.

Required range: 1 <= x <= 100

use_video_bpm

boolean

default:true

Weight matches toward the video's detected tempo.

creative_direction

string

A plain-language brief, e.g. "warm, cinematic, no vocals".

Maximum string length: 500

era

string

mood

string

vocals

string

include_sync

boolean

default:false

Attach sync_status and sync_points to every match. CACHE-ONLY: it never builds a profile, so an un-indexed track comes back warming with an empty sync_points array. On a freshly ingested video that is most of the shortlist. Cue starts a background index for those tracks, so a later call usually returns them warm. Use /v1/align when you need the index built now.

sync_points_per_track

integer

default:4

How many sync points to return per track when they are warm.

Required range: 1 <= x <= 12

Response

A ranked shortlist of matches.

video_id

string

lane

object

Show child attributes

Overview

Endpoints

Match music to a video

Authorizations

Headers

Query Parameters

Body

Response