Music

Watches a video, works out what it should sound like, then searches and scores real sounds from that video’s own network. $0.25 per call. 35 seconds against a familiar niche, up to 150 seconds the first time it meets an unfamiliar one.

The catalogue is chosen by the video’s network, not by a parameter. A Douyin creator cannot place a TikTok sound and vice versa, so a suggestion from the wrong catalogue would be impossible to act on rather than merely weak.

Request

string

required

Link to the video to match sounds against.

number

default:"10"

How many suggestions to return, 1 to 20. Does not change the price: cost is set by how many sounds are listened to and judged, which is fixed.

boolean

default:"false"

Restrict to Commercial Music Library tracks. Set this for business accounts, which can only legally use cleared audio.

Response

string

Which catalogue was searched, tiktok or douyin.

object

{ id, url, durationSec } for the video analyzed.

object[]

Ranked sounds, best fit first.

Show suggestion

string

Sound id. Douyin ids are namespaced douyin:<id>.

string | null

Sound title.

string | null

Track artist or original creator.

string | null

Artwork.

string | null

Streamable audio. Expires within hours.

string

Link to the sound on its platform.

number | null

Full track length.

number | null

The slice usable in an edit.

object | null

Structured reading of the audio: tempo, energy, mood.

object

Usage trajectory, so you can tell a rising sound from a fading one.

object

Commercial Music Library status and rights flags.

object

Why this sound suits this video, with a score.

number

Ranking key. Fit dominant, with a bounded trend bonus.

string[]

Caveats worth surfacing, never errors.

number

How many sounds were scored to produce this list.

string[]

Honest notes about the run, for example when the pool was thinner than usual.

Example

curl -X POST https://nouvelhq.com/api/v1/music \
  -H "Authorization: Bearer $NOUVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.douyin.com/video/7615947954167303458", "limit": 5}'

const music = await fetch('https://nouvelhq.com/api/v1/music', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.NOUVEL_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ url, limit: 5, requireCommercial: true }),
  signal: AbortSignal.timeout(300_000),
}).then((r) => r.json())

Response (truncated)

{
  "market": "douyin",
  "video": { "id": "douyin:7615947954167303458", "url": "https://www.douyin.com/video/7615947954167303458", "durationSec": 28 },
  "suggestions": [
    {
      "soundId": "douyin:7444264218973898762",
      "title": "活力四射energetic",
      "author": "阿祥",
      "durationSec": 108,
      "shootDurationSec": 60,
      "fit": { "score": 8, "why": "Matches the fast cuts and the upbeat close" },
      "finalScore": 8.4,
      "warnings": []
    }
  ],
  "considered": 17,
  "notes": []
}

Notes

First call in a new niche is slow. Sounds we have never heard have to be listened to. Those readings are cached permanently, so the same niche is much faster afterwards.
No usable sound is a 200 with an empty array and no charge.
Preview URLs expire, usually within hours.
On Douyin there is no genre metadata to draw on, so fit is judged from the audio itself.

Getting started

Concepts

API reference

Request

Response

Example

Notes

​Request

​Response

​Example

​Notes

Request

Response

Example

Notes