POST /v1/songs/uploads/:id/transcribe

Listen to an upload again, or listen to a Remove vocals upload so you can reimagine it

You rarely need this: a Reimagine upload is transcribed automatically. Call it to:

retry after status: "failed", or when a transcription has gone quiet for more than 3 minutes;
reimagine a song you uploaded for Remove vocals. That upload was confirmed for the recording only, so confirm the Reimagine statements here too.

While a transcription is running (and for 3 minutes after it started) this returns the upload unchanged instead of starting a second one, and charges nothing.

Cost

Situation	Cost
Listening to a Remove vocals upload so you can reimagine it	1 credit — counts toward the first Reimagine (1 more, so 2 in total)
The first retry after `status: "failed"`	Free (the failed transcription's credit was already refunded)
Any later retry after a failure	1 credit, refunded if it fails too
Transcribing again after `transcribed` or `no_vocals`	1 credit
Resubmitting a transcription that went quiet for over 3 minutes	Free — it runs on the credit already charged

The upload's pricing.retranscribeCredits says which applies. Without enough credits you get 402 INSUFFICIENT_CREDITS and nothing is started.

Request

POST https://pub.finetuning.ai/v1/songs/uploads/:id/transcribe

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	`application/json`

Path parameters

Parameter	Type	Description
`id`	string	The upload ID from `POST /v1/songs/uploads`

Body parameters

Parameter	Type	Required	Description
`attestationVersion`	string	Only for a Remove vocals upload	The current rights statement version (`"2026-09-30"`)
`attestationConfirmed`	boolean	Only for a Remove vocals upload	`true` — your end user saw the Reimagine statements and confirmed them

Send attestationConfirmed: true only after your end user has seen the Reimagine statements from GET /v1/songs/config and confirmed them.

Example request

curl -X POST https://pub.finetuning.ai/v1/songs/uploads/6b232256-e036-42f5-8cc7-49049cea1da4/transcribe \
  -H "X-API-Key: ft_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "attestationVersion": "2026-09-30", "attestationConfirmed": true }'

await fetch(`https://pub.finetuning.ai/v1/songs/uploads/${uploadId}/transcribe`, {
  method: 'POST',
  headers: { 'X-API-Key': process.env.FINETUNING_API_KEY!, 'Content-Type': 'application/json' },
  body: JSON.stringify({ attestationVersion: '2026-09-30', attestationConfirmed: true }),
})

Response

200 OK — the upload object, usually with status: "transcribing". Poll GET /v1/songs/uploads/:id for the result.

Errors

Code	Status	Description
`ATTESTATION_REQUIRED`	400	A Remove vocals upload without the Reimagine confirmation
`INSUFFICIENT_CREDITS`	402	This transcription costs 1 credit and there's none left. Nothing was started
`PAID_PLAN_REQUIRED`	403	Not on a paid plan
`NOT_FOUND`	404	No upload with that id on your account
`CATALOGUE_MATCH`	409	The upload was blocked
`UPLOAD_EXPIRED`	410	The upload's 24 hours are up

POST /v1/songs/uploads/:id/transcribe

On this page