---
title: "Create a lyric video or Create a Canvas"
method: POST
path: "/api/v1/videos"
tags: ["videos"]
---

# Create a lyric video or Create a Canvas

`POST /api/v1/videos`

## Request

- Base URL: `https://kinetune.com`
- URL: `https://kinetune.com/api/v1/videos`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://kinetune.com/api/auth/oauth2/authorize`, token URL `https://kinetune.com/api/auth/oauth2/token`, scopes: `videos:write`)

Make the lyric video a quote priced (spends credits)

Send the same request as the quote plus its quote_id. Returns the video ids at once; poll get_video until status is completed (or failed). Each video has one file per format.

Make the Canvas a quote priced (spends credits)

Send the same request as the quote plus its quote_id. Returns the video ids at once; poll get_video until status is completed. Upload the file in Spotify for Artists.

## Request body

- union
  - object
    - `type` 'lyric-video', required
    - `song_id` string, required: The song id
    - `variations` integer: 1–4 different New Looks, one video each (an Existing Look renders one)
    - `callback_url` string: An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
    - `metadata` object: Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
    - `look` union, required: {"mode":"existing","id":"look_…"} to reuse a saved Look (add "lyric_style" to render it in another lyric style, at no extra cost), or {"mode":"new","category":"…","lyric_style":"…","background":{"source":"ai-image","quality":"high"},"visibility":"private","direction":"…"} to have one designed (background.source "upload-photo"/"upload-video" with background.upload_id from upload_background designs it around your own media; such a Look stays private. "stock-photo"/"stock-video" with background.stock_id from search_stock uses that stock photo or clip instead of the director's pick). lyric_style (optional, from get_options) sets how the lyrics are presented and animated: block-stack, punch, player, neon, terminal, cinematic… Omit it and the director picks one. background.scenes (2–4, AI image only) makes that many shots of the same world that cut on the song's sections, each priced like the first. The singer is left out unless asked: feature_artist "always" (default "never") makes them the subject of the background, recognizable from their artist photos (add_artist_photos); it needs an AI image or AI video background, a private Look and display.cover false (the cover would hide them), and that Look then only serves this artist's songs. A saved Look that shows an artist (featured_artist) only serves that artist's songs, also with display.cover false
      - object
        - `mode` 'new', required
        - `category` 'release' | 'fall' | 'halloween' | 'christmas' | 'summer' | 'valentines' | 'mood' | 'retro' | 'synthwave' | 'street' | 'nature' | 'luxury' | 'abstract' | 'minimal' | 'neon' | 'pop-art' | 'lo-fi' | 'grunge' | 'cosmic' | 'cyber' | 'dreamy', required
        - `background` object
          - `source` 'ai-image' | 'ai-video' | 'stock-photo' | 'stock-video' | 'upload-photo' | 'upload-video' | 'designed'
          - `quality` 'standard' | 'high' | 'ultra'
          - `upload_id` string
          - `scenes` integer
          - `stock_id` string
        - `visibility` 'private' | 'public'
        - `direction` string
        - `feature_artist` 'never' | 'always'
        - `lyric_style` 'showcase' | 'block-stack' | 'punch' | 'depth-scatter' | 'neon' | 'terminal' | 'cinematic' | 'player' | 'lo-fi' | 'zine' | 'glitch' | 'pop-art' | 'dreamy' | 'chrome' | 'visualizer' | 'minimal' | 'outline' | 'messages' | 'vinyl' | 'album' | 'tv' | 'cube' | 'cassette' | 'phone' | 'glass' | 'embers' | 'ink' | 'smoke' | 'stardust' | 'drip' | 'rain' | 'screen' | 'behind' | 'big-type'
      - object
        - `mode` 'existing', required
        - `id` string, required
        - `lyric_style` 'showcase' | 'block-stack' | 'punch' | 'depth-scatter' | 'neon' | 'terminal' | 'cinematic' | 'player' | 'lo-fi' | 'zine' | 'glitch' | 'pop-art' | 'dreamy' | 'chrome' | 'visualizer' | 'minimal' | 'outline' | 'messages' | 'vinyl' | 'album' | 'tv' | 'cube' | 'cassette' | 'phone' | 'glass' | 'embers' | 'ink' | 'smoke' | 'stardust' | 'drip' | 'rain' | 'screen' | 'behind' | 'big-type'
    - `aspect_ratios` string[]: Formats to render, each its own file: "9:16" (vertical), "16:9" (wide), "1:1" (square)
    - `display` object: Which elements show (title, artist, cover, lyrics, badges, headline) and their sizes. cover must be false to show the artist in the background
      - `title` boolean
      - `artist` boolean
      - `cover` boolean
      - `lyrics` boolean
      - `badges` boolean
      - `headline` 'none' | 'new-release' | 'out-now' | 'coming-soon' | 'listen-now'
      - `cover_scale` number
      - `text_scale` number
      - `artist_scale` number
      - `spacing_scale` number
    - `trim` object: Render only this section of the song (at least 8 seconds)
      - `start_seconds` number, required
      - `end_seconds` number, required
    - `quote_id` string, uuid, required: The quote_id from the matching quote: the request must be identical
  - object
    - `type` 'canvas', required
    - `song_id` string, required: The song id
    - `variations` integer: 1–4 different Canvases
    - `callback_url` string: An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
    - `metadata` object: Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
    - `source` 'ai-video' | 'ai-image' | 'stock-photo' | 'stock-video': ai-video (default), ai-image, stock-photo or stock-video
    - `quality` 'standard' | 'high': AI video model tier: standard or high
    - `resolution` '720p' | '1080p': 1080p (1080×1920) or 720p
    - `style` 'cinematic' | 'dreamy' | 'abstract' | 'surreal' | 'retro' | 'minimal' | 'dark' | 'vibrant' | 'nature' | 'urban': Optional visual style
    - `direction` string: Optional mood, motifs or references; the concept still comes from the cover
    - `feature_artist` 'auto' | 'always' | 'never': Whether the Canvas shows the artist: auto (the director decides), always or never (AI sources; needs artist photos for "always")
    - `seconds` integer: Canvas length in whole seconds, 5–8 (default 8). Spotify loops it, so no part of the song is chosen
    - `stock_id` string: With a stock source: the stock photo or video (search_stock with seconds) to use instead of the director's pick
    - `quote_id` string, uuid, required: The quote_id from the matching quote: the request must be identical

## Response `200`

OK

## Other responses

- `201`: Created
- `400`: Invalid request
- `401`: Missing or invalid credentials
- `402`: Not enough credits
- `403`: Missing scope
- `404`: Not found
- `409`: Conflict
- `422`: Unprocessable
- `503`: Temporarily unavailable (AI video): nothing was held; try again after Retry-After seconds

---

[API](https://skmtc.dev/kinetune/apis/kinetune-api.md) · [All operations](https://skmtc.dev/kinetune/apis/kinetune-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kinetune/apis/kinetune-api/revisions/372c8e87d1ff?raw)