> ## Documentation Index > Fetch the complete documentation index at: https://cue.vibeset.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Match music to a script > Cue Underscore: match licensed music to a text **script** (no video). Paste the script and get a ranked shortlist of ten licensed tracks, each with a title, artist, tempo, its catalog ids and a why-it-fits map showing which words pulled which sound. Synchronous: there's no video ingest or per-minute analysis, so the result returns inline. Billed flat per call, and a call that returns no tracks isn't billed. The shortlist size is fixed and is not a request field. Like every other endpoint, this returns identity and analysis rather than audio. Accounts granted `preview` also get a short-lived watermarked link on each track. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/underscore openapi: 3.1.0 info: title: Cue API version: 1.0.0 description: > Match licensed music to a video, or to a script. Five things it does: **match** music to an analyzed video, **underscore** a text script with no video at all, **sync** a track to the moments in a clip, **loop** a short track across a long one, and map a track's **beats** and downbeats. Videos are ingested once and reused by match, sync and loop; underscore and beats take no video at all. Responses carry timings and catalog identifiers, not recordings. You resolve a track through your own catalog access and render it yourself. Work that is already cached answers `200`. Work that needs a first-time build answers `202`, in one of two shapes: a JOB (`job_id` plus a job URL) or a VIDEO STILL INGESTING (`video_id` and a `/v1/videos/{id}` URL, with no `job_id`). Branch on whether `job_id` is present. All requests authenticate with an API key, sent either as `Authorization: Bearer vbsk_...` or in an `x-api-key` header. Both work. Keys are created in the [developer portal](https://cue.vibeset.ai/developer). servers: - url: https://cue.vibeset.ai description: Production security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Match description: Match music to a video. - name: Underscore description: Match music to a script, no video needed. - name: Sync description: Get sync points, where a track lands with a video. - name: Loop description: Loop a short track seamlessly across a long video. - name: Beats description: Map the beat and downbeat grid of any audio you can point us at. - name: Videos description: Ingest and check the status of videos. paths: /v1/underscore: post: tags: - Underscore summary: Match music to a script description: > Cue Underscore: match licensed music to a text **script** (no video). Paste the script and get a ranked shortlist of ten licensed tracks, each with a title, artist, tempo, its catalog ids and a why-it-fits map showing which words pulled which sound. Synchronous: there's no video ingest or per-minute analysis, so the result returns inline. Billed flat per call, and a call that returns no tracks isn't billed. The shortlist size is fixed and is not a request field. Like every other endpoint, this returns identity and analysis rather than audio. Accounts granted `preview` also get a short-lived watermarked link on each track. operationId: underscoreScript parameters: - name: expand in: query required: false description: >- Set to `full` for the full track object plus the lane's candidate pool. schema: type: string enum: - full - name: Idempotency-Key in: header required: false description: > Suppresses a DUPLICATE BILLING ROW for a retry of this exact request. It does not return the earlier response and does not stop the call re-running. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnderscoreRequest' examples: basic: summary: Score a short-form script value: script: >- You've been folding your shirts wrong your whole life. Here's the fold in three moves. Follow for the ones they don't teach you. with_platform: summary: Steer with a platform hint + brief value: script: Three things I do before 7am to actually own my day. platform: tiktok creative_direction: upbeat, driving, no vocals responses: '200': description: A ranked shortlist of tracks, each with a why-it-fits map. content: application/json: schema: $ref: '#/components/schemas/UnderscoreResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '502': $ref: '#/components/responses/UpstreamError' components: schemas: UnderscoreRequest: type: object required: - script properties: script: type: string minLength: 1 maxLength: 7000 description: The script to score. Kept under the 8KB request limit. platform: type: string maxLength: 40 description: >- A free-form hint passed into the brief. `tiktok`, `reels`, `shorts`, `linkedin` and `youtube` are the vocabulary it is written for. Nothing rejects another value, and an unrecognised one is simply a weaker steer. creative_direction: type: string maxLength: 500 description: A plain-language brief, e.g. "warm, upbeat, no vocals". era: type: string mood: type: string vocals: type: string UnderscoreResult: type: object properties: lane: $ref: '#/components/schemas/UnderscoreLane' example: lane: title: Your shortlist reasoning: >- A clean, modern rhythmic bed that lands the turn without crowding the read. matches: - track_id: '14792' audio_id: '60184' soundstripe_song_id: '14792' soundstripe_audio_file_id: '60184' title: Skeptical artist_name: Lincoln Davis score: 0.98 bpm: 120 instrumental: true duration_seconds: 164.01 match_map: - video: punchy hook audio: driving 120 BPM score: 1 - video: confident tone audio: bright synths score: 1 UnderscoreLane: type: object properties: title: type: - string - 'null' reasoning: type: - string - 'null' matches: type: array items: $ref: '#/components/schemas/UnderscoreMatch' candidate_pool: type: array description: Present only with `?expand=full`. items: $ref: '#/components/schemas/UnderscoreMatch' Error: type: object description: Every `/v1` error body has this shape. properties: error: type: object properties: type: type: string enum: - invalid_request - authentication_error - payment_required - forbidden - not_found - conflict - payload_too_large - unsupported_media_type - rate_limited - internal_error - upstream_error - service_unavailable - error description: >- A stable machine-readable type. Branch on this, not on the message. message: type: string description: A human-readable explanation of what went wrong. request_id: type: - string - 'null' description: >- The same value as the `X-Request-Id` response header. Quote it to support. details: type: array description: >- Present only on a request-validation `422`, listing which fields were invalid. items: type: object example: error: type: invalid_request message: Provide either 'video_id' or 'video_url'. request_id: a1b2c3d4e5f6 UnderscoreMatch: type: object description: One matched track for a script, with its why-it-fits map. properties: track_id: type: string description: The matched track. Same value as `soundstripe_song_id`. audio_id: type: - string - 'null' soundstripe_song_id: type: - string - 'null' description: >- The track's Soundstripe catalog id, same value as `track_id`, named so it's unambiguous to resolve. soundstripe_audio_file_id: type: - string - 'null' description: >- The Soundstripe audio-file id for this track, same value as `audio_id`. title: type: - string - 'null' description: Track title, present on the default response, no expand needed. artist_name: type: - string - 'null' score: type: number description: Match strength, 0–1. bpm: type: - number - 'null' instrumental: type: - boolean - 'null' duration_seconds: type: - number - 'null' preview: $ref: '#/components/schemas/TrackPreview' description: > Absent unless your account was granted `preview`. No audio is attached by default. match_map: type: array description: Why this track fits, script phrases patched to the sounds they pull. items: $ref: '#/components/schemas/MatchMapLink' TrackPreview: type: object description: > A signed, directly playable link to the track's full watermarked MP3. **Only present on accounts granted `preview`**. The default is to attach no audio at all, because the only audio Cue can serve is watermarked and watermarked audio can't go into a finished video. When present it's minted per request with a short TTL: play it or fetch it, don't store the URL. Re-request to get a fresh one. properties: url: type: string format: uri expires_at: type: string format: date-time description: When THIS link stops working. format: type: string example: mp3 duration_seconds: type: - number - 'null' MatchMapLink: type: object description: One "why it fits" link, a script phrase tied to a sonic trait. properties: video: type: string description: A short phrase from the script (the "in the script" side). audio: type: string description: A trait of how the track sounds (the "in the track" side). score: type: number description: Link strength, 0–1. category: type: string responses: BadRequest: description: The request was malformed. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: The key is missing, invalid, expired or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: > No active payment method, the credit grant is exhausted or expired, or the monthly spend cap was reached. `error.message` names which. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The key can't access this resource, the video or job belongs to another account. content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: > A field is invalid (then `error.details` lists which), or the video failed to process and should be re-submitted. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. See the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: description: Requests allowed per minute. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' UpstreamError: description: The work itself failed. Retry, and contact us if it persists. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your API key as a Bearer token, e.g. `Authorization: Bearer vbsk_live_...` apiKeyAuth: type: apiKey in: header name: x-api-key description: 'Your API key in the x-api-key header, e.g. `x-api-key: vbsk_live_...`' ````