POST /v1/instrumental

Generate an instrumental music track from a text description and submit it to the generation queue. Returns immediately with a processing status — the rendered audio arrives via webhook or by polling GET /v1/generations/:id.

Instrumental tracks are produced by a dedicated instrumental-only model. There are no vocals, lyrics, BPM, key, scale, or time-signature controls — the model reads your description and picks the instrumentation and tempo for you.

There is no GET /v1/instrumental. Instrumental tracks live in the same store as music — to list or fetch them, use GET /v1/generations?type=instrumental and GET /v1/generations/:id.

Instrumental generations draw from the same monthly credit pool as music. API keys already require a Pro or Lifetime plan, so any valid key can generate them.

Request

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

Headers

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

Body parameters

Parameter	Type	Required	Default	Description
`prompt`	string	Yes	—	Description of the track (max 700 chars)
`duration`	number	No	`120`	Length in seconds. Range 30–210, snapped to 15 s steps. Free tier capped at 120; paid up to 210
`enhance`	boolean	No	`true`	Expand your short description into a full music prompt before generating. Set `false` to use your words verbatim
`seed`	number	No	—	Seed for reproducibility. Omit for a random seed
`webhook`	string	No	—	HTTPS URL we'll POST the completed (or failed) track to. Skips polling. Max 2048 chars. Identified by `User-Agent: finetuning-webhook/1.0`. See the Webhooks guide
`certificate`	boolean	No	`false`	`true` issues a generation certificate for this track the moment it completes, and returns a download URL on your webhook. See Certificates below

Example request

curl -X POST https://pub.finetuning.ai/v1/instrumental \
  -H "X-API-Key: ft_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "dreamy lofi piano with soft vinyl crackle",
    "duration": 120,
    "enhance": true,
    "seed": 1234567,
    "webhook": "https://your-app.com/finetuning-callback?token=YOUR_SECRET"
  }'

Response

202 Accepted

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "processing",
    "type": "instrumental",
    "prompt": "dreamy lofi piano with soft vinyl crackle",
    "parameters": { "duration": 120, "seed": 1234567 },
    "webhook": null,
    "certificate": false,
    "creditsRemaining": 1952,
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

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

Response fields

Field	Type	Description
`data.id`	string	Unique generation ID (UUID)
`data.status`	string	`processing`, `pending`, `completed`, `failed`
`data.type`	string	Always `instrumental` for this endpoint
`data.prompt`	string	The prompt used
`data.parameters.duration`	number	Requested duration in seconds (after snapping)
`data.parameters.seed`	number	Seed used for generation
`data.webhook`	string \| null	Echo of the `webhook` URL we accepted, or `null` if not provided
`data.certificate`	boolean	Echo of the `certificate` flag we accepted
`data.creditsRemaining`	number	Credits remaining after this generation
`data.createdAt`	string	ISO 8601 timestamp

When you read an instrumental track back, its parameters.bpm, parameters.keyscale, and parameters.timesignature are null — the model chooses them. duration and seed are always present.

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 — at https://pub.finetuning.ai/v1/generations/:id/certificate, since instrumental tracks live in the same store as music.

You only need the flag if you delete tracks after archiving them. If you keep your tracks, leave it off and call GET /v1/generations/:id/certificate whenever you need the PDF.

certificate must be a real JSON boolean — we accept true and nothing else, and the response's data.certificate confirms what we accepted. Certificates are free and never cost a credit.

Length & tiers

Instrumental tracks run 30–210 seconds, snapped to the nearest 15 s step. The free tier is capped at 120 seconds; Pro and Lifetime can go up to the full 210. The server clamps anything out of range and snaps to the nearest valid length.

Errors

Code	Status	Description
`VALIDATION_ERROR`	400	Invalid parameters (check `message` field for details)
`MISSING_API_KEY`	401	X-API-Key header was not provided
`INVALID_API_KEY`	401	API key is malformed, revoked, or does not exist
`MONTHLY_LIMIT_REACHED`	402	No generations remaining this month
`PRO_PLAN_REQUIRED`	403	Your subscription does not include API access
`RATE_LIMITED`	429	Too many requests on a read endpoint — wait and retry (60/min/user)
`GENERATION_RATE_LIMITED`	429	Too many `POST /v1/instrumental` calls — wait and retry (10/min/user)
`QUEUE_FULL`	429	Too many generations in progress
`GENERATION_FAILED`	500	Generation queue submission failed

On this page