POST /v1/generations Create a new music generation
Start generating an AI music track with the specified parameters. Deducts one credit and submits to the generation queue.
POST https://pub.finetuning.ai/v1/generations Header Type Required Description X-API-Keystring Yes Your API key Content-Typestring Yes application/json
Parameter Type Required Default Description tagsstring Yes — Music description (max 700 chars) lyricsstring No — Lyrics text (max 2000 chars) durationnumber No 60Track duration in seconds (5–210; free tier capped at 120) bpmnumber No 120Beats per minute (60–200) languagestring No — Language code (en, ja, de, fr, es, zh, ko, pt, it, ru) keystring No auto Musical key (C, C#, D, ... B) scalestring No auto Scale type (major, minor) timesignaturestring No "4"Time signature (2–7) seednumber No — Seed for reproducibility webhookstring 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 for payload shape and how to secure your endpoint.
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" }' { "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" , "creditsRemaining" : 1952 , "createdAt" : "2025-01-15T10:30:00Z" } } If webhook was not provided, the field is returned as null.
Field Type Description data.idstring Unique generation ID data.statusstring processing, pending, completed, faileddata.promptstring The tags/prompt used data.parameters.bpmnumber BPM of the track data.parameters.durationnumber Requested duration in seconds data.parameters.timesignaturestring Time signature data.parameters.languagestring Language code data.parameters.keyscalestring Combined key and scale (e.g., "C minor") data.parameters.seednumber Seed used for generation data.webhookstring | null Echo of the webhook URL we accepted, or null if not provided data.creditsRemainingnumber Credits remaining after this generation data.createdAtstring ISO 8601 timestamp
Code Status Description VALIDATION_ERROR400 Invalid parameters (check message field for details) MISSING_API_KEY401 X-API-Key header was not provided INVALID_API_KEY401 API key is malformed, revoked, or does not exist MONTHLY_LIMIT_REACHED402 No generations remaining this month PRO_PLAN_REQUIRED403 Your subscription does not include API access RATE_LIMITED429 Too many requests on a read endpoint — wait and retry (60/min/user) GENERATION_RATE_LIMITED429 Too many POST /v1/generations calls — wait and retry (10/min/user) QUEUE_FULL429 Too many generations in progress GENERATION_FAILED500 Generation queue submission failed
