---
title: "Upload a song"
method: POST
path: "/api/v1/songs"
tags: ["songs"]
---

# Upload a song

`POST /api/v1/songs`

## Request

- Base URL: `https://kinetune.com`
- URL: `https://kinetune.com/api/v1/songs`
- 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: `music:write`, `videos:write`)

Add a song: master audio and square cover art

Audio: MP3, WAV or M4A up to 250 MB. Cover: a square JPEG or PNG, 1000–6000 px (3000×3000 recommended), up to 20 MB; it is kept at 1536, 640 and 160 px, not as uploaded. The song is analyzed next (lyrics, beats, sections): poll get_song until analysis.status is "ready", usually about a minute. Pass lyrics (or set them later with set_song_lyrics) to have the videos spell every word right.

## Request body

- object
  - `artist_id` string, required: The artist id
  - `title` string, required: The song title
  - `language` string: Lyrics language (ISO 639-1, e.g. "en"); detected when omitted
  - `audio_url` string, uri: A public https URL of the master audio
  - `cover_art_url` string, uri: A public https URL of the square cover art
  - `lyrics` string: Optional. The song’s lyrics as text: plain (Suno-style [Verse]/[Chorus] tags and (x2) marks are fine), or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio: your text fixes misheard words and sets where lines break in videos. A part sung again (a chorus) can be written once; lyrics that don’t match what’s sung, or cover only part of it, are refused once the song is analyzed (get_song: analysis.lyrics.status "mismatch")

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