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

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,
    "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.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.

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