REST API

BasicsCopy Anchor Link

Every operation, with its fields, answers and a playground for the read-only ones, is in the API reference.

Song lyricsCopy Anchor Link

A song’s words are transcribed from the audio, so one may be misheard. Give it its own lyrics as lyrics when you add it, or later with POST /songs/{id}/lyrics: plain text ([Verse] and [Chorus] tags are fine) or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio; the text fixes the spelling and where lines break. Lyrics that don’t match what’s sung are refused (409) and nothing changes; DELETE goes back to the transcription. analysis.lyrics.status says whose words the videos show.

Your own backgroundCopy Anchor Link

POST /backgrounds takes your photo or video; a New Look with background.source upload-photo or upload-video and its upload_id is designed around it, with no media cost. Such a Look stays private.

Stock you chooseCopy Anchor Link

GET /stock?kind=photo&q=…&orientation=portrait searches stock photos or clips (24 a page; landscape when 16:9 is among the formats, seconds for a Canvas clip). A stock source with look.background.stock_id (or a Canvas’s stock_id) uses that item instead of the director’s pick, which drops the pick from the quote. Credit the photographer wherever you show an item.

ImagesCopy Anchor Link

Kept at the sizes they're used at, not as uploaded: a song's cover_art.url (1536 px JPEG), preview_url (640 px) and thumbnail_url (160 px WebP); an artist photo's url (1536 px) and thumbnail_url; a Look's backgrounds.previews (480 px wide). Image links are signed for 7 days and stay the same all day, so they cache well.

Lyric stylesCopy Anchor Link

A New Look takes look.lyric_style: how the lyrics are presented and animated (block-stack, punch, player, neon, terminal…). GET /options lists them; leave it out and the director picks one. An Existing Look takes it too, to render the same design in another style at no extra cost. GET /looks?lyric_style= filters the Library.

ScenesCopy Anchor Link

An AI image background can be 2–4 shots of the same world that cut on the song’s sections: look.background.scenes (1 by default). Each scene is priced like the first.

Music videosCopy Anchor Link

"type": "music-video": the song’s artist performs it, lip-synced, in an AI music video made from their photos, so the artist needs photos first (without them the quote is a 400 on song_id).

• scenes, for the places the brief leaves open: {"mode":"invent"} by default (the director imagines every place) or {"mode":"stock"} (it finds a real stock photo of each place, empty of people, and the artist is put into it). PATCH /music-video-plans/:id/places/:n swaps one found place’s photo.
• quality, the resolution: one of the qualities GET /options lists for the model, 768p by default; 1080p is the same video sharper for about twice the credits. It isn’t part of the plan.
• model, one of Kinetune’s music video models: one-take by default, MiniMax H3 Max. music_video.models in GET /options lists each with the categories, styles, formats, photo slots and length it makes, and a request outside them is a 400.
• category (performance by default, cinematic, story, surreal), style (optional; the director picks one from the cover), aspect_ratio (one file: 9:16 by default, 16:9 or 1:1), trim (15 seconds to 10 minutes; omitted, the whole song, which must be 15 seconds to 10 minutes long), direction, cast and variations.

direction names kit pieces by their @handle ("the @blue-set on the @rooftop"): the artist’s outfits and the workspace’s places and props, added with POST /kit from an upload, a file_url or a stock_id, with an optional crop rectangle (fractions of the image). A mentioned piece is used exactly as it is and the director designs the rest; a handle that isn’t in the kit is a 400 that names it, and a video takes up to the model’s kit limits. Words in (parentheses) in the lyrics are backing vocals: sung off camera, never lip-synced.

cast picks the two photos the artist is kept from: face_photo_id (a sharp face, mouth visible) and outfit_photo_id (the outfit worn throughout); either left out, the director picks it. A photo uploaded with hidden: true stays off the artist’s photos and works in cast, for one music video only.

The shot list first, free: POST /music-video-plans with the same fields returns in about a minute the concept, the cast, the world every shot keeps and each shot’s times, lyrics and action; "revise": {"plan_id": "plan_…", "note": "…"} rewrites it with a note.

Optional, a lookbook before the shot list: POST /music-video-lookbooks with the same fields designs one for free (the director’s outfits drawn on the artist, places drawn empty, props alone, beside the brief’s own pieces); POST /music-video-lookbooks/:id/render with credits (its price.draw.credits) draws the pictures, held and charged as each is drawn; keep, redraw or redesign pieces, then write the shot list with lookbook_id.

Quote and create with song_id and plan_id, and the video is made from exactly that plan. It is made in shots and priced by them: setup, creative direction and making the shots (credits.music_video.models in GET /options is a minute by each model). MiniMax H3 Max makes shots of up to about 14 seconds, cut between the song’s lines and made side by side, joined with a cut, the director’s transition or (with takes: "continuous") a continuous take; it usually takes 5 to 20 minutes; stages preparing, directing, generating, delivering. Once planned, the video’s music_video is its plan, in the same shape. Cancel stops the generation; retry runs the same plan, or plans afresh without one.

Photo referencesCopy Anchor Link

look.background.references "stock" (AI image or AI video; "none" by default) only with feature_artist "always": the background is one real stock photo of a place that the director finds, with the artist put into it; the description is rewritten around the photo, and only its light, colour and mood shift toward the Look and your direction. No extra cost.

ExamplesCopy Anchor Link

curl -s https://kinetune.com/api/v1/quotes -H "Authorization: Bearer $KINETUNE_API_KEY" \
  -H "content-type: application/json" -d '{
    "type": "lyric-video", "song_id": "SONG_ID", "aspect_ratios": ["9:16", "16:9"],
    "look": { "mode": "new", "category": "street", "lyric_style": "punch" }
  }'

curl -s https://kinetune.com/api/v1/music-video-plans -H "Authorization: Bearer $KINETUNE_API_KEY" \
  -H "content-type: application/json" -d '{
    "song_id": "SONG_ID", "category": "cinematic", "style": "neon-night",
    "aspect_ratio": "16:9", "trim": { "start_seconds": 62.5, "end_seconds": 92.5 }
  }'

curl -s https://kinetune.com/api/v1/quotes -H "Authorization: Bearer $KINETUNE_API_KEY" \
  -H "content-type: application/json" -d '{ "type": "music-video", "song_id": "SONG_ID", "plan_id": "PLAN_ID" }'

curl -s https://kinetune.com/api/v1/songs -H "Authorization: Bearer $KINETUNE_API_KEY" \
  -F artist_id=ARTIST_ID -F title="Midnight Drive" \
  -F [email protected] -F [email protected]