POST /v1/sound-effects

Generate a short AI sound effect and submit it to the generation queue. Returns immediately with a processing status — the rendered audio arrives via webhook or by polling GET /v1/sound-effects/:id.

Sound effects are a paid-plan feature. API keys already require a Pro or Lifetime plan, so any valid key can generate them.

Request

POST https://pub.finetuning.ai/v1/sound-effects

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 sound effect (max 700 chars)
`duration`	number	No	`4`	Length in seconds. Clamped to 1–8, snapped to 0.5 s steps
`enhance`	boolean	No	`true`	Let the model expand your prompt for better results. Set `false` to use your prompt verbatim
`webhook`	string	No	—	HTTPS URL we'll POST the completed (or failed) sound effect 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/sound-effects \
  -H "X-API-Key: ft_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "thunderclap with heavy rain",
    "duration": 5,
    "enhance": true,
    "webhook": "https://your-app.com/finetuning-callback?token=YOUR_SECRET"
  }'

Response

202 Accepted

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "processing",
    "prompt": "thunderclap with heavy rain",
    "requestedDuration": 5,
    "webhook": "https://your-app.com/finetuning-callback?token=YOUR_SECRET",
    "dailyRemaining": 99,
    "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 sound-effect ID (UUID)
`data.status`	string	`processing`, `pending`, `completed`, `failed`
`data.prompt`	string	The prompt used
`data.requestedDuration`	number	Requested duration in seconds (after clamping)
`data.webhook`	string \| null	Echo of the `webhook` URL we accepted, or `null` if not provided
`data.dailyRemaining`	number	Sound effects remaining in today's allowance
`data.createdAt`	string	ISO 8601 timestamp

Daily limit

Sound effects are metered by a shared daily cap of 100 per UTC day. Generations created through the API and through the web app draw from the same pool — you can't double your allowance by switching channels. Every successful response returns dailyRemaining; once it hits zero you'll get DAILY_LIMIT_REACHED until the next UTC day.

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
`PRO_PLAN_REQUIRED`	403	Your subscription does not include API access
`DAILY_LIMIT_REACHED`	429	Daily sound-effect allowance used up — try again tomorrow
`RATE_LIMITED`	429	Too many requests on a read endpoint — wait and retry (60/min/user)
`GENERATION_RATE_LIMITED`	429	Too many `POST /v1/sound-effects` 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