# Music API migration

Source: https://recoupable.dev/docs/api-reference/music/legacy

Use the current background music-generation API; distinguish unfinished specialized outcomes from retired REST paths.

## Generate a song now

Use [`POST /api/music`](https://recoupable.dev/docs/api-reference/music/generate) with a prompt and lyrics.
It returns `202` with a generation record; poll
[`GET /api/music/{generationId}`](https://recoupable.dev/docs/api-reference/music/get) for completion and
the resulting audio URL. It does not return audio in the initial response.
See the current reference for accepted settings, account scope and credits.

## Former music routes

The six POST paths below are retired from the callable specification because
they have no implemented handlers in the current API. They are not aliases for
`POST /api/music`. Their specialized outcomes are not equivalent to ordinary
song generation and are not declared canceled by this correction.

| Former path | Current choice and remaining limit |
| --- | --- |
| `/api/music/compose` | Use the current generation API for a prompt-and-lyrics song. Composition-plan input and an immediate binary-audio response are not supported replacements. |
| `/api/music/compose/detailed` | Use generation status/result reads for the fields actually returned. Multipart audio and word-level timestamps are not established by that result. |
| `/api/music/plan` | No hosted structured-composition-plan replacement is established. A locally prepared plan is not a supported request field, and the old free-operation claim is withdrawn. |
| `/api/music/stream` | Poll for the completed audio URL. The current API does not establish playback of partial audio chunks while the song is generated. |
| `/api/music/video-to-music` | No hosted upload-video-to-soundtrack replacement is established. Do not send video files to the prompt-and-lyrics endpoint. |
| `/api/music/stem-separation` | No hosted stem-separation replacement is established. Generating a new song does not split an existing recording into stems. |

## What remains undecided

[Reconciliation #327](https://github.com/recoupable/mono/issues/327) retains the
specialized capability decisions. The current music-generation implementation
is tracked in [App #1992](https://github.com/recoupable/app/issues/1992) and
[API #848](https://github.com/recoupable/api/pull/848); it is not delivery of every
former capability. An agent or local skill may help prepare inputs, but that
does not establish a hosted route or compatibility with the former request.

This is a reference correction. No provider run or audio-quality check was
performed to make these availability statements.