> ## 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. # Poll an align job > Poll an align job returned by `POST /v1/align`. `202` while it is still running. `200` with the sync points once complete, plus `job_id`, `status` and `cached`. Billed once, on completion. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/align/jobs/{job_id} 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/align/jobs/{job_id}: get: tags: - Sync summary: Poll an align job description: > Poll an align job returned by `POST /v1/align`. `202` while it is still running. `200` with the sync points once complete, plus `job_id`, `status` and `cached`. Billed once, on completion. operationId: getAlignJob parameters: - name: job_id in: path required: true schema: type: string responses: '200': description: The finished alignment. content: application/json: schema: $ref: '#/components/schemas/AlignJobResult' '202': description: Still processing. Poll again. content: application/json: schema: $ref: '#/components/schemas/AlignJob' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '502': $ref: '#/components/responses/UpstreamError' components: schemas: AlignJobResult: type: object description: A completed align job, an AlignResult plus the job's own fields. properties: video_id: type: string track_id: type: string job_id: type: string status: type: string enum: - complete cached: type: boolean sync_points: type: array items: $ref: '#/components/schemas/SyncPoint' mix: $ref: '#/components/schemas/Mix' description: >- Present only when `auto_mix` was true AND the measurement could be read. Unlike the synchronous `AlignResult`, the job OMITS this key rather than sending null. AlignJob: type: object description: >- A cold alignment running as a job. Poll `poll` until `status` is `complete`. properties: video_id: type: string track_id: type: string description: Present on the submit response. job_id: type: string status: type: string example: processing poll: type: string example: /v1/align/jobs/run_9f2c next: type: string SyncPoint: type: object description: A moment where the music lands with the video. properties: offset_seconds: type: number description: Seconds into the song that sits under the start of the video. score: type: number description: Strength of the hit, 0–1. label: type: - string - 'null' description: > What lands here, e.g. "Drop", "Phrase", "Downbeat". Null on a track that could only be aligned by energy, and an empty string for a mid-song beat-sync point. Mix: type: object description: >- Auto-mix (duck-the-music-under-the-voiceover) spec, returned when `auto_mix` is true. These are the same numbers the Cue app's Loop/Sync preview + export use, so a render with them matches the app. Applicable to whatever music you lay under the clip. properties: voiceover: type: boolean description: >- True when the video has a sustained, measured voiceover to duck under. classification: type: string description: >- The video's own audio, classified, `voice` / `ambient` / `silent` / `none`. music_gain_db: type: number description: >- Suggested gain (dB) to sit the music under the voice. Present only when `voiceover` is true. video_gain_db: type: number description: >- Suggested gain (dB) to bring the footage voice up. Present only when `voiceover` is true. duck: type: - object - 'null' description: >- How to duck the music during speech. Null when there's no voiceover. Apply in this order: footage audio at `video_gain_db`, then music at `music_gain_db`, then `envelope_points` as further attenuation on the music only, then sum and limit. properties: envelope_points: type: array description: >- THE AUTHORITATIVE CURVE: `[[t_seconds, gain_db], ...]`, the same automation Cue's own renderer replays. Each `gain_db` is a POSITIVE amount to pull the music DOWN at that instant: `0` is untouched, `20` is 20 dB below where `music_gain_db` left it. INTERPOLATE LINEARLY between points. That reproduces the curve exactly. Points are emitted only where the curve moves, so held passages cost nothing. items: type: array items: type: number envelope_hz: type: integer description: >- The grid the points were sampled on (the curve's resolution, not its length). You do not need it to render, because the points carry their own timestamps. speech_ranges: type: array description: >- Voiceover spans `[start, end]` in seconds where the music should duck. items: type: array items: type: number depth_db: type: number description: >- NOMINAL full-depth excursion, as a POSITIVE magnitude in dB. Ramp lengths are computed per gap, so this describes a full-depth move and nothing else. A short pause gets a shallower, faster one. Rendering from this instead of `envelope_points` gives an audibly cruder mix than Cue's. attack_ms: type: integer description: >- NOMINAL fade-down time entering a speech span, in ms. See `depth_db`. release_ms: type: integer description: >- NOMINAL fade-up time leaving a speech span, in ms. See `depth_db`. example: voiceover: true classification: voice music_gain_db: -4.4 video_gain_db: 11.4 duck: envelope_points: - - 0 - 20 - - 1.2 - 20 - - 1.9 - 0 - - 4.8 - 0 envelope_hz: 40 speech_ranges: - - 1.2 - 4.8 - - 9.5 - 14.1 depth_db: 20 attack_ms: 375 release_ms: 1425 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 responses: Unauthorized: description: The key is missing, invalid, expired or revoked. 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' NotFound: description: No such video or job. 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_...`' ````