POST /v1/generations

Start generating an AI music track with the specified parameters. Deducts one credit and submits to the generation queue.

Request

POST https://pub.finetuning.ai/v1/generations

Headers

Body parameters

Example request

curl -X POST https://pub.finetuning.ai/v1/generations \
  -H "X-API-Key: ft_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": "lofi chill piano night",
    "duration": 120,
    "bpm": 85,
    "key": "C",
    "scale": "minor",
    "language": "en",
    "timesignature": "4",
    "seed": 1234567,
    "webhook": "https://your-app.com/finetuning-callback?token=YOUR_SECRET"
  }'

Response

{
  "data": {
    "id": "gen_xyz789",
    "status": "processing",
    "prompt": "lofi chill piano night",
    "parameters": {
      "bpm": 85,
      "duration": 120,
      "timesignature": "4",
      "language": "en",
      "keyscale": "C minor",
      "seed": 1234567
    },
    "webhook": "https://your-app.com/finetuning-callback?token=YOUR_SECRET",
    "certificate": false,
    "creditsRemaining": 1952,
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

If webhook was not provided, the field is returned as null.

Response fields

Certificates

Set certificate: true to have a generation certificate issued the moment the track completes. The completion webhook then carries the certificate's number, its public verification URL and a download URL for the PDF.

{
  "tags": "lofi chill piano night",
  "certificate": true,
  "webhook": "https://your-app.com/finetuning-callback?token=YOUR_SECRET"
}

You only need this if you delete tracks after archiving them: a certificate is rendered from the generation, so it can't be produced once the generation is gone. If you keep your tracks, leave the flag off and call GET /v1/generations/:id/certificate whenever you need the PDF.

Two things worth knowing:

• It must be a real JSON boolean. We accept true and nothing else — the string "true" is read as "no certificate". The response's data.certificate is how you confirm what we accepted.
• Certificates are free. Requesting one never costs a credit, and a certificate that fails to issue never stops the track being delivered.

See Certificates for the webhook payload and the archiving pattern.

Vocal gender

Set vocalGender to female or male to steer the singing voice. It only affects tracks that have lyrics — an instrumental has no voice to steer.

{
  "tags": "modern pop, clean production, catchy melody",
  "lyrics": "[verse]\nCity lights are fading out tonight",
  "vocalGender": "female"
}

Three things are worth knowing before you rely on it:

• It is a strong steer, not a guarantee. In our own blind testing the requested gender was never inverted, but a small share of takes come out with the vocal too indistinct to call. If a take is wrong, generate again — a different seed usually resolves it.
• data.prompt comes back rewritten. We prepend the vocal phrasing to your tags, and the response echoes what was actually used. Store data.prompt if you want to reproduce a track exactly.
• Re-sending a returned prompt is safe. If you feed data.prompt back in as tags with a different vocalGender, the previous phrasing is replaced rather than stacked, so the two never conflict.

Omitting the field, or sending auto, leaves generation exactly as it was before this option existed.

Errors