> ## 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.

# Quickstart

> Match music to a video in five minutes.

From a new key to a ranked shortlist for one of your videos. About five minutes.

<Steps>
  <Step title="Create a key">
    In the [developer portal](https://cue.vibeset.ai/developer), add a payment method under
    **Billing**, then click **Create key**. Copy it when it appears, because it's shown only once.

    If we sent you a credit code, redeem it under **Billing** instead and skip the card: a live
    credit grant funds your calls and a trial account can hold two live keys. See
    [Starting credits](/docs/credits). Otherwise a key needs a card behind it, because every call runs
    real analysis against the licensed catalog. You're billed per call at the rates in
    [Metering & pricing](/docs/metering-and-pricing).
  </Step>

  <Step title="Ingest a video">
    Point Cue at a public video URL: a direct link, or a share link (Google Drive,
    Dropbox, S3, a CDN) that redirects to the file. Cue fetches the clip, analyzes it,
    and returns a `video_id` to poll.

    ```bash theme={null}
    curl https://cue.vibeset.ai/v1/videos \
      -H "x-api-key: vbsk_live_..." \
      -H "content-type: application/json" \
      -d '{"video_url": "https://yourcdn.com/clip.mp4"}'
    ```

    ```json 202 theme={null}
    { "video_id": "69e5a58e73370adad5a10dc9", "status": "processing", "poll": "/v1/videos/69e5a58e73370adad5a10dc9" }
    ```
  </Step>

  <Step title="Wait until the ingest finishes">
    Poll the video until its status is `ready`.

    ```bash theme={null}
    curl https://cue.vibeset.ai/v1/videos/69e5a58e73370adad5a10dc9 \
      -H "x-api-key: vbsk_live_..."
    ```

    ```json 200 theme={null}
    {
      "video_id": "69e5a58e73370adad5a10dc9",
      "status": "ready",
      "ready": true,
      "title": "clip",
      "reason": null
    }
    ```

    `status` is `processing`, `ready` or `failed`. On a failure `reason` names the cause in a form
    you can branch on, such as `insufficient_credits`. On every other status it is `null`.
  </Step>

  <Step title="Match the music">
    Now ask for a shortlist.

    ```bash theme={null}
    curl https://cue.vibeset.ai/v1/match \
      -H "x-api-key: vbsk_live_..." \
      -H "content-type: application/json" \
      -d '{"video_id": "69e5a58e73370adad5a10dc9", "top_k": 5}'
    ```

    This answers one of two ways, so branch on the status code.

    A video Cue has already analyzed under your account's engine comes back `200` with the lane:

    ```json 200 theme={null}
    {
      "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.0, "bpm": 120,
            "instrumental": true, "duration_seconds": 164.01 }
        ]
      }
    }
    ```

    Anything else comes back `202` with a job:

    ```json 202 theme={null}
    {
      "video_id": "69e5a58e73370adad5a10dc9",
      "status": "processing",
      "job_id": "run_9f2c…",
      "poll": "/v1/match/jobs/run_9f2c…",
      "next": "Poll the job until status is 'complete', then read its lane + matches."
    }
    ```

    Poll `GET /v1/match/jobs/run_9f2c…` until `status` is `complete`. The completed job carries the
    same `lane` as the `200` above, plus `job_id` and `status`. Polling is free and the match is
    billed once, when the job completes.
  </Step>
</Steps>

<Warning>
  A freshly ingested video usually takes the `202` branch. `ready` means the ingest finished, not
  that the engine analysis behind `/v1/match` has landed. Cue flips the row to `ready` first and
  persists that analysis after. So write the `202` branch on day one rather than treating it as
  the rare case.
</Warning>

Each `track_id` resolves in your catalog, and it is the Soundstripe song id. Add `?expand=full`
to the match request for titles, tags, energy and the candidate pool inline.

## Where to go next

You now have a `video_id` and a `track_id`. Everything else takes one or both.

<CardGroup cols={2}>
  <Card title="Match" icon="wand-magic-sparkles" href="/docs/match">
    Steer the shortlist, or match straight from a URL.
  </Card>

  <Card title="Find where to cut" icon="scissors" href="/docs/sync">
    Sync points for a track against your clip.
  </Card>

  <Card title="Loop over long video" icon="repeat" href="/docs/loop">
    Cover a clip that runs longer than the song.
  </Card>

  <Card title="Underscore a script" icon="pen-nib" href="/docs/underscore">
    Match music to words, with no video at all.
  </Card>
</CardGroup>

## What it costs

Every call is metered. See [Metering & pricing](/docs/metering-and-pricing) for the per-call rates.
Analysis is charged once per video at ingest and reused by every later match, sync and loop
against it, so the expensive step happens once. A call that errors bills nothing. Set a monthly
spend cap in the [portal](https://cue.vibeset.ai/developer) if you want a hard ceiling.