Create a music project

Start a Text-to-Music project from a creative brief. Returns the project and its arrangement job.

POST /sound_clone/api/v1/music/projects

curl --location 'https://api.myvocal.ai/sound_clone/api/v1/music/projects' \
--header 'accessKey: <your_api_key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 6f1c1f0e0b8a4d1e' \
--data '{
  "description": "An upbeat summer pop song about a road trip along the coast.",
  "genre": "POP",
  "styleNotes": "Bright synths, driving drums, warm bass.",
  "moods": ["UPLIFTING", "ENERGETIC"],
  "vocalLanguage": "en",
  "durationSec": 90,
  "lyricsMode": "AUTO",
  "vocalStyle": "BRIGHT_ENERGETIC"
}'

200 Success

{
  "code": 1,
  "message": "success",
  "data": {
    "projectId": "mup_...",
    "projectStatus": "ARRANGEMENT_GENERATING",
    "job": { "jobId": "muj_...", "jobType": "ARRANGEMENT", "status": "QUEUED" },
    "requestId": "..."
  }
}

Creates the project and immediately queues the arrangement stage. This is asynchronous: the response does not contain a song.

Header

accessKey · string · required

API key for authentication.

Idempotency-Key · string · required

Unique per distinct operation: 16–64 printable ASCII characters. Same key with the same body replays safely; same key with a different body is rejected with 47008.

Body

description · string · required

What the song is about. 1–800 code points.

genre · string · required

One of the values from capabilities.genres.

styleNotes · string

Optional production notes, 0–120 code points. null is normalized to "".

moods · array · required

1–3 distinct values from capabilities.moods.

vocalLanguage · string · required

A code from capabilities.supportedVocalLanguages (for example en).

durationSec · number · required

One of capabilities.supportedDurationsSec: 60, 90, 120 or 180.

lyricsMode · string · required

AUTO or CUSTOM. With AUTO, customLyrics must be absent or empty.

customLyrics · string

Required content only with lyricsMode: "CUSTOM" (20–2800 code points). Normalized to null under AUTO.

vocalStyle · string · required

One of the values from capabilities.vocalStyles.

Response

projectId · string

Stable project identifier. Keep it — it is your recovery anchor.

projectStatus · string

ARRANGEMENT_GENERATING right after creation.

job · object

{ jobId, jobType: "ARRANGEMENT", status: "QUEUED" }.

curl --location 'https://api.myvocal.ai/sound_clone/api/v1/music/projects' \
--header 'accessKey: <your_api_key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 6f1c1f0e0b8a4d1e' \
--data '{
  "description": "An upbeat summer pop song about a road trip along the coast.",
  "genre": "POP",
  "styleNotes": "Bright synths, driving drums, warm bass.",
  "moods": ["UPLIFTING", "ENERGETIC"],
  "vocalLanguage": "en",
  "durationSec": 90,
  "lyricsMode": "AUTO",
  "vocalStyle": "BRIGHT_ENERGETIC"
}'

200 Success

{
  "code": 1,
  "message": "success",
  "data": {
    "projectId": "mup_...",
    "projectStatus": "ARRANGEMENT_GENERATING",
    "job": { "jobId": "muj_...", "jobType": "ARRANGEMENT", "status": "QUEUED" },
    "requestId": "..."
  }
}

A replay is not the first response replayed byte-for-byte: it re-reads the current project and may return the full project detail instead. Use projectId to query the resource.

Common errors

• code = 47001: the brief failed validation (unknown enum, wrong duration, mood list empty or duplicated, description out of range).
• code = 47008: the Idempotency-Key was reused with a different body.
• code = 47011: temporarily unavailable — retry with backoff.
• code = 47018: Text-to-Music is not available for this account or cohort.