GET /v1/sound-effects/:id

Retrieve the full details of a specific sound effect, including its current status and download URL.

Request

GET https://pub.finetuning.ai/v1/sound-effects/:id

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Path parameters

Parameter	Type	Description
`id`	string	The sound-effect ID returned by `POST /v1/sound-effects`

Example

curl https://pub.finetuning.ai/v1/sound-effects/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "X-API-Key: ft_live_your_key_here"

Response

200 OK

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "completed",
    "prompt": "thunderclap with heavy rain",
    "requestedDuration": 5,
    "audioUrl": "https://media.finetuning.ai/sfx/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/0.mp3",
    "duration": 5.0,
    "webhook": null,
    "errorMessage": null,
    "createdAt": "2025-01-15 10:30:00",
    "completedAt": "2025-01-15T10:30:06.184Z"
  }
}

Response fields

Field	Type	Description
`data.id`	string	Unique sound-effect ID (UUID)
`data.status`	string	`pending`, `processing`, `completed`, `failed`
`data.prompt`	string	The prompt used
`data.requestedDuration`	number	Requested duration in seconds
`data.audioUrl`	string \| null	Audio download URL (available when `completed`)
`data.duration`	number \| null	Actual length of the rendered clip in seconds
`data.webhook`	string \| null	Webhook URL set at create time, or `null` if none
`data.errorMessage`	string \| null	Error details if generation failed
`data.createdAt`	string	Creation timestamp
`data.completedAt`	string \| null	Completion timestamp (ISO 8601)

Sound-effect statuses

Status	Description
`pending`	Generation is queued
`processing`	Generation is in progress
`completed`	Generation finished — `audioUrl` is available
`failed`	Generation failed — check `errorMessage` field for details

Sound effects generate in a few seconds. Poll this endpoint until the status flips to completed. If you'd rather not poll, set a webhook URL when you create the sound effect and we'll deliver the result to you — see Webhooks.

async function waitForSoundEffect(id, apiKey) {
  while (true) {
    const res = await fetch(`https://pub.finetuning.ai/v1/sound-effects/${id}`, {
      headers: { 'X-API-Key': apiKey },
    });
    const { data } = await res.json();

    if (data.status === 'completed') return data;
    if (data.status === 'failed') throw new Error(data.errorMessage);

    // Wait 2 seconds before polling again
    await new Promise(r => setTimeout(r, 2000));
  }
}

Errors

Code	Status	Description
`MISSING_API_KEY`	401	X-API-Key header was not provided
`INVALID_API_KEY`	401	API key is malformed, revoked, or does not exist
`NOT_FOUND`	404	Sound effect not found
`INTERNAL_ERROR`	500	Unexpected server error