Music

Songs with vocals from lyrics, instrumentals, and lyrics written for you.

There are two tiers:

Tier	Songs	Instrumentals
`standard`	Up to 5 minutes. `seconds` is the upper bound; the song takes the time the lyrics need.	Up to 2 minutes, exactly `seconds` long.
`studio`	Up to 10 minutes. Follows your sections to the second, with styles per section.	Up to 10 minutes, exactly `seconds` long.

After a song is made, Cinara checks which lyric lines were sung (output.lyricCheck).

Endpoints:

GET /v1/music/options
POST /v1/music/lyrics
POST /v1/music
GET /v1/music/{id}
GET /v1/music/{id}/files/{name}

Get music options

GET /v1/music/options

Response

200 OK

json

{
  "credits": { "standardSongPerSecond": 20, "standardInstrumental": 300, "studioPerSecond": 100, "lyrics": 100 },
  "limits": {
    "minSeconds": 10,
    "standardSongMaxSeconds": 300,
    "standardInstrumentalMaxSeconds": 120,
    "studioMaxSeconds": 600,
    "styleMaxChars": 1000
  },
  "sectionLimits": {
    "maxSections": 30,
    "minSectionSeconds": 3,
    "maxSectionSeconds": 120,
    "maxLineChars": 200,
    "maxLyricChars": 3500,
    "maxTotalSeconds": 600
  },
  "ideaMaxChars": 600,
  "styleExamples": [
    "Upbeat modern pop, bright female vocals, punchy drums, 118 BPM, summer feeling",
    "Lo-fi hip hop, soft piano, vinyl crackle, mellow bass, 80 BPM"
  ]
}

styleExamples is shortened above.

Credits

Free.

Example

bash

curl https://api.cinara.ai/v1/music/options \
  -H "Authorization: Bearer $CINARA_API_KEY"

Write lyrics

POST /v1/music/lyrics

Writes original lyrics, a style and song sections from an idea. It finishes within the request.

Needs a verified phone.

The result is ready to pass as style and sections to Create music.

Request body

Field	Type	Required	Description
`idea`	string	yes	What the song is about. 5–600 characters. Naming well-known artists is refused.
`language`	string	no	The lyrics' language, 1–40 characters. Default `English`.
`seconds`	number	no	Target song length, 30–600. Default 120.

Response

201 Created

json

{
  "song": {
    "title": "Paper Boats",
    "style": "Acoustic folk, warm male vocals, fingerpicked guitar, gentle, 90 BPM",
    "sections": [
      { "name": "Intro", "lines": [], "styles": [], "seconds": 8 },
      {
        "name": "Verse 1",
        "lines": ["Folded from the morning news", "Sailing where the gutters run", "Every puddle on the avenue", "Is an ocean for someone"],
        "styles": [],
        "seconds": 22
      },
      {
        "name": "Chorus",
        "lines": ["Paper boats, carry me home", "Down the rain to where I'm from"],
        "styles": [],
        "seconds": 18
      }
    ]
  },
  "credits": 49900
}

Up to 30 sections, up to 16 lines each, each line up to 200 characters.
Section lengths are 3–120 seconds and are scaled to add up to about seconds.
The response has no generation, but the request is recorded in History with module music_lyrics.

Errors

Status	`error`	Message
400	`invalid_request`	`Describe the song idea in a few words`
400	`invalid_request`	`Keep the idea under 600 characters`
400	`invalid_request`	`Choose a language`
400	`invalid_request`	`Choose a length from 30 seconds to 10 minutes`
400	`invalid_request`	`Cinara writes original songs. Describe the idea without naming a well-known artist.`
402	`insufficient_credits`	`This needs 100 credits`
403	`phone_unverified`	`Verify your phone number to start creating.`
502	`generation_failed`	`The lyrics couldn't be written. Your credits were refunded; try again.`

Credits

100 credits per request. Refunded if writing fails.

Example

bash

curl -X POST https://api.cinara.ai/v1/music/lyrics \
  -H "Authorization: Bearer $CINARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idea": "A child sailing paper boats in the monsoon rain", "language": "English", "seconds": 90}'

Create music

POST /v1/music

Starts making a song or an instrumental.

Needs a verified phone.

Request body

Field	Type	Required	Description
`kind`	string	no	`song` (default) or `instrumental`. Any other value makes a song.
`tier`	string	no	`standard` (default) or `studio`. Any other value is `standard`.
`style`	string	yes	Genre, instruments, vocals, mood, tempo. 1–1,000 characters. Naming well-known artists is refused.
`avoid`	string[]	no	Styles to keep out. The first 8 are used, each up to 60 characters; longer is refused.
`sections`	object[]	songs	The song's lyrics and structure. Ignored for instrumentals.
`sections[].name`	string	yes	Such as `Verse 1` or `Chorus`. 1–60 characters.
`sections[].lines`	string[]	no	Sung lines, each up to 200 characters. Blank lines are dropped.
`sections[].styles`	string[]	no	Styles for this section (used by `studio`). The first 8 are used, each up to 60 characters; longer is refused.
`sections[].seconds`	number	yes	The section's length, 3–120.
`seconds`	number	see below	The length in seconds.
`title`	string	no	Up to 80 characters; longer is refused. Used as the file label.

Rules for songs:

Up to 30 sections, with at least one sung line.
All lyrics together up to 3,500 characters.
For studio, the song's length is the sum of the sections' seconds (10–600) and seconds is ignored.

Rules for seconds:

Kind and tier	`seconds`
Standard song	Required. Upper bound, 10–300.
Standard instrumental	Required. Exact length, 10–120.
Studio song	Ignored.
Studio instrumental	Required. Exact length, 10–600.

Response

201 Created

json

{
  "generation": {
    "id": "0b8f6d2e-5c1a-4e7b-9f3d-2a6c8e1b4d70",
    "module": "music",
    "status": "running",
    "input": {
      "kind": "song",
      "tier": "standard",
      "style": "Acoustic folk, warm male vocals, fingerpicked guitar, gentle, 90 BPM",
      "avoid": ["electric guitar"],
      "sections": [
        { "name": "Verse 1", "lines": ["Folded from the morning news", "Sailing where the gutters run"], "styles": [], "seconds": 20 },
        { "name": "Chorus", "lines": ["Paper boats, carry me home", "Down the rain to where I'm from"], "styles": [], "seconds": 20 }
      ],
      "seconds": 90,
      "title": "Paper Boats",
      "fileName": "paper-boats.mp3",
      "plannedSeconds": 90
    },
    "output": { "stage": "queued", "step": 1, "stageLabel": "Composing" },
    "credits": 1800,
    "error": null,
    "created_at": "2026-09-15T10:42:07.512341+00:00",
    "completed_at": null
  },
  "credits": 48100
}

Errors

Status	`error`	Message
400	`invalid_request`	`Add at least one section`
400	`invalid_request`	`Use up to 30 sections`
400	`invalid_request`	`Give every section a name of up to 60 characters`
400	`invalid_request`	`"Chorus" must last 3 to 120 seconds`
400	`invalid_request`	`A line in "Chorus" is longer than 200 characters`
400	`invalid_request`	`Add some lyrics, or make an instrumental`
400	`invalid_request`	`Keep the lyrics under 3,500 characters`
400	`invalid_request`	`The song can be up to 10 minutes`
400	`invalid_request`	`Describe the music`
400	`invalid_request`	`Keep the description under 1,000 characters`
400	`invalid_request`	`Keep the title under 80 characters`
400	`invalid_request`	`Keep each style and each thing to avoid under 60 characters`
400	`invalid_request`	`Make it at least 10 seconds long`
400	`invalid_request`	`Standard songs can be up to 5 minutes` (also `Standard instrumentals can be up to 2 minutes`, `Studio songs can be up to 10 minutes`, `Studio instrumentals can be up to 10 minutes`)
400	`invalid_request`	`Describe the sound instead of naming a well-known artist.`
402	`insufficient_credits`	`This needs 1,800 credits`
403	`phone_unverified`	`Verify your phone number to start creating.`
502	`generation_failed`	`The music couldn't start. Your credits were refunded.`

Credits

Kind and tier	Reserved	Final
Standard song	`ceil(seconds × 20)`	`ceil(seconds made × 20)`, never more than reserved
Standard instrumental	300 per track	300
Studio (song or instrumental)	`ceil(planned seconds × 100)`	Same as reserved

Refunded if the music can't be made.

Example

bash

curl -X POST https://api.cinara.ai/v1/music \
  -H "Authorization: Bearer $CINARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "song",
    "tier": "standard",
    "title": "Paper Boats",
    "style": "Acoustic folk, warm male vocals, fingerpicked guitar, gentle, 90 BPM",
    "avoid": ["electric guitar"],
    "sections": [
      {"name": "Verse 1", "lines": ["Folded from the morning news", "Sailing where the gutters run"], "seconds": 20},
      {"name": "Chorus", "lines": ["Paper boats, carry me home", "Down the rain to where I am from"], "seconds": 20}
    ],
    "seconds": 90
  }'

Get a music job

GET /v1/music/{id}

Checks a music job, moves it forward, and returns it with its file once finished.

Songs have two steps: Composing, then Checking the lyrics. Instrumentals have one.

Response

200 OK

json

{
  "generation": {
    "id": "0b8f6d2e-5c1a-4e7b-9f3d-2a6c8e1b4d70",
    "module": "music",
    "status": "succeeded",
    "input": {
      "kind": "song",
      "tier": "standard",
      "style": "Acoustic folk, warm male vocals, fingerpicked guitar, gentle, 90 BPM",
      "avoid": ["electric guitar"],
      "sections": [
        { "name": "Verse 1", "lines": ["Folded from the morning news", "Sailing where the gutters run"], "styles": [], "seconds": 20 },
        { "name": "Chorus", "lines": ["Paper boats, carry me home", "Down the rain to where I'm from"], "styles": [], "seconds": 20 }
      ],
      "seconds": 90,
      "title": "Paper Boats",
      "fileName": "paper-boats.mp3",
      "plannedSeconds": 90
    },
    "output": {
      "step": 2,
      "durationSeconds": 88.4,
      "lyricCheck": {
        "heardShare": 0.96,
        "lines": [
          { "section": "Verse 1", "text": "Folded from the morning news", "heardShare": 1 },
          { "section": "Verse 1", "text": "Sailing where the gutters run", "heardShare": 0.8 },
          { "section": "Chorus", "text": "Paper boats, carry me home", "heardShare": 1 },
          { "section": "Chorus", "text": "Down the rain to where I'm from", "heardShare": 1 }
        ]
      }
    },
    "credits": 1768,
    "error": null,
    "created_at": "2026-09-15T10:42:07.512341+00:00",
    "completed_at": "2026-09-15T10:44:01.207733+00:00"
  },
  "files": [
    {
      "name": "song",
      "label": "Paper Boats",
      "contentType": "audio/mpeg",
      "size": 3538944,
      "url": "https://api.cinara.ai/media/1789511327/k3JH9…/workspaces/…/music/0b8f6d2e-5c1a-4e7b-9f3d-2a6c8e1b4d70/song.mp3"
    }
  ],
  "credits": 48132
}

Field	Description
`output.durationSeconds`	The length made.
`output.lyricCheck`	Songs only. `heardShare` is the share of lyric words heard in order (0–1), overall and per line.
`files`	One file, named `song` or `instrumental`, labelled with the title (or `Song` / `Instrumental`). Empty until the job succeeds.

Failures: Music took too long and was stopped. or The music couldn't be made.

Errors

Status	`error`	Message
404	`not_found`	`Not found`

Credits

Free to read.

Polling example

bash

while :; do
  RES=$(curl -s "https://api.cinara.ai/v1/music/$ID" -H "Authorization: Bearer $CINARA_API_KEY")
  STATUS=$(echo "$RES" | jq -r .generation.status)
  [ "$STATUS" != "running" ] && break
  echo "$(echo "$RES" | jq -r .generation.output.stageLabel)…"
  sleep 10
done
echo "$RES" | jq '{status: .generation.status, error: .generation.error, lyrics: .generation.output.lyricCheck.heardShare, files: .files}'

Download a music file

GET /v1/music/{id}/files/{name}

Downloads the finished track (song or instrumental) as an attachment.

Response

200 OK with the file and Content-Disposition: attachment; filename="paper-boats-song.mp3".

Errors

Status	`error`	Message
404	`not_found`	`File not found`

Credits

Free.

Example

bash

curl -L "https://api.cinara.ai/v1/music/0b8f6d2e-5c1a-4e7b-9f3d-2a6c8e1b4d70/files/song" \
  -H "Authorization: Bearer $CINARA_API_KEY" -o paper-boats.mp3

Music ​

Get music options ​

Response ​

Credits ​

Example ​

Write lyrics ​

Request body ​

Response ​

Errors ​

Credits ​

Example ​

Create music ​

Request body ​

Response ​

Errors ​

Credits ​

Example ​

Get a music job ​

Response ​

Errors ​

Credits ​

Polling example ​

Download a music file ​

Response ​

Errors ​

Credits ​

Example ​

Music

Get music options

Response

Credits

Example

Write lyrics

Request body

Response

Errors

Credits

Example

Create music

Request body

Response

Errors

Credits

Example

Get a music job

Response

Errors

Credits

Polling example

Download a music file

Response

Errors

Credits

Example