Edit the arrangement

Edit an arrangement by merging the editable fields into the current immutable arrangement.

PUT /sound_clone/api/v1/music/projects/{projectId}/arrangement

curl --location --request PUT 'https://api.myvocal.ai/sound_clone/api/v1/music/projects/mup_.../arrangement' \
--header 'accessKey: <your_api_key>' \
--header 'Content-Type: application/json' \
--data '{
  "expectedVersion": 1,
  "title": "Coast Road",
  "styleSummary": "Bright summer pop with driving drums.",
  "tempoBpm": 118,
  "sections": [
    { "sectionId": "<section_id>", "lyrics": "Where the highway meets the sea...", "styleNotes": "Warm pads" }
  ]
}'

200 Success

{
  "code": 1,
  "message": "success",
  "data": {
    "projectId": "mup_...",
    "version": 2,
    "arrangement": { "durationSec": 90, "sections": [ "..." ], "requestId": "..." }
  }
}

The body is an edit request, not a whole arrangement. The service merges your edit into the current immutable arrangement and re-validates the result.

Header

accessKey · string · required

API key for authentication.

Path

projectId · string · required

The project identifier.

Body

expectedVersion · number · required

The arrangementVersion you based this edit on. A mismatch is rejected with 47016.

title · string

Song title, 1–120 code points.

styleSummary · string

Summary of the musical style, 1–500 code points.

tempoBpm · number

null, or between 40 and 220.

sections · array · required

Sections to merge, addressed by sectionId: { sectionId, lyrics, styleNotes }, in section order.

Validation rules

The merged arrangement must satisfy:

• 4–12 sections; every section position must equal its 1-based index.
• Section types: INTRO, VERSE, PRE_CHORUS, CHORUS, BRIDGE, OUTRO, OTHER.
• Each section durationSec is 5–60, and the durations must sum to the arrangement duration.
• At least one VERSE and one CHORUS must be present.
• Concatenated lyrics, trimmed, must be 20–2800 code points.

Response

projectId · string

Project identifier.

version · number

The new arrangement version.

arrangement · object

The merged, validated arrangement.

curl --location --request PUT 'https://api.myvocal.ai/sound_clone/api/v1/music/projects/mup_.../arrangement' \
--header 'accessKey: <your_api_key>' \
--header 'Content-Type: application/json' \
--data '{
  "expectedVersion": 1,
  "title": "Coast Road",
  "styleSummary": "Bright summer pop with driving drums.",
  "tempoBpm": 118,
  "sections": [
    { "sectionId": "<section_id>", "lyrics": "Where the highway meets the sea...", "styleNotes": "Warm pads" }
  ]
}'

200 Success

{
  "code": 1,
  "message": "success",
  "data": {
    "projectId": "mup_...",
    "version": 2,
    "arrangement": { "durationSec": 90, "sections": [ "..." ], "requestId": "..." }
  }
}

Editing the arrangement makes the current quote stale. Request a new quote before generating.

Common errors

• code = 47016: expectedVersion does not match the current arrangement version. Re-read the project and retry.
• code = 47001: the merge produced an arrangement that violates a validation rule.
• code = 47009: the project does not exist or is not owned by your account.