GET /v1/generations/:id

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

This endpoint also returns instrumental tracks — check the type field to tell them apart.

Request

GET https://pub.finetuning.ai/v1/generations/:id

Headers

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

Path parameters

Parameter	Type	Description
`id`	string	The generation ID (e.g., `gen_abc123`)

Example

curl https://pub.finetuning.ai/v1/generations/gen_abc123 \
  -H "X-API-Key: ft_live_your_key_here"

Response

200 OK

{
  "data": {
    "id": "gen_abc123",
    "title": "modern country instrumental",
    "prompt": "modern country instrumental, acoustic guitar strumming, pedal steel guitar, fiddle melody",
    "type": "music",
    "status": "completed",
    "audioUrl": "https://media.finetuning.ai/audio/gen_abc123.mp3",
    "duration": 120,
    "fileSize": null,
    "isPublic": false,
    "playCount": 0,
    "downloadCount": 0,
    "likeCount": 0,
    "parameters": {
      "bpm": 110,
      "duration": 120,
      "keyscale": "G major",
      "timesignature": 4,
      "seed": 1951074202
    },
    "errorMessage": null,
    "generationTime": 17,
    "createdAt": "2025-01-15 10:30:00",
    "completedAt": "2025-01-15T10:30:17.623Z"
  }
}

Response fields

Field	Type	Description
`data.id`	string	Unique generation ID
`data.title`	string	Generation title
`data.prompt`	string	The tags/prompt used
`data.type`	string	`music`, `instrumental`, `reimagine` or `remove_vocals`
`data.status`	string	`pending`, `processing`, `completed`, `failed`
`data.audioUrl`	string \| null	Audio download URL (available when `completed`)
`data.duration`	number	Track duration in seconds
`data.fileSize`	number \| null	Audio file size in bytes
`data.isPublic`	boolean	Whether the generation is publicly visible
`data.playCount`	number	Number of plays
`data.downloadCount`	number	Number of downloads
`data.likeCount`	number	Number of likes
`data.parameters`	object	Generation parameters (bpm, duration, keyscale, timesignature, seed). For `instrumental` tracks, `bpm`, `keyscale`, and `timesignature` are `null`
`data.errorMessage`	string \| null	Error details if generation failed
`data.generationTime`	number \| null	Time taken to generate in seconds
`data.createdAt`	string	Creation timestamp
`data.completedAt`	string \| null	Completion timestamp (ISO 8601)

Generation 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

Reimagine and Remove vocals tracks

type is reimagine or remove_vocals for tracks made from an upload (Reimagine & Remove vocals). Those tracks are always isPublic: false, and GET /v1/generations/:id/certificate answers 403 PRIVATE_ONLY for them.

Polling for completion

Since generation is asynchronous, poll this endpoint to check when your track is ready. If you'd rather not poll, set a webhook URL when you create the generation and we'll deliver the result to you — see Webhooks.

async function waitForGeneration(id, apiKey) {
  while (true) {
    const res = await fetch(`https://pub.finetuning.ai/v1/generations/${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	Resource not found
`INTERNAL_ERROR`	500	Unexpected server error

On this page