# synthDrum > Part of the MAP Audio Music API docs. Index of every page: https://map.audio/developers/music-api/llms.txt. OpenAPI document: https://map.audio/developers/music-api/openapi.json. `POST https://api.map.audio/v1/synth/drum` Render procedural drum engines with named controls and timed triggers. Synthesize drum hits with one of PAM's drum-synth engines (kick, snare, hats, 808 and more), set by named controls in real units, with trigger times for a pattern of hits. It is free; GET /v1/drum-engines lists the engines and their controls. Free: it counts in GET /v1/usage, never in render-minutes. Answers 200 with the finished job when it ends within `Prefer: wait=N` (30 s unless sent, at most 60), else 202 with the job to poll. Auth: `Authorization: Bearer` with an API key or a map.audio access token. Send `Prefer: wait=N` (0 to 60) to receive the finished job when it ends within N seconds; otherwise the answer is `202` with the job. Send `Idempotency-Key` to retry safely: the same key and body return the same result for 24 hours. MCP tool: `synth_drum`. ## Body | Field | Type | Required | Description | | --- | --- | --- | --- | | `engine` | "1" \| "kick" \| "2" \| "snare" \| "3" \| "hihat" \| "4" \| "clap" \| "5" \| "tom" \| "6" \| "fm" \| "7" \| "cymbal" \| "8" \| "cowbell" \| "9" \| "808" \| "10" \| "shaker" \| "11" \| "rim" \| "12" \| "conga" \| "13" \| "bell" \| "14" \| "pluck" \| "15" \| "zap" \| "16" \| "wave" \| "17" \| "chaos" \| "18" \| "stab" \| "19" \| "acoustic-kick" \| "20" \| "acoustic-snare" \| "21" \| "acoustic-cymbal" \| "22" \| "acoustic-hi-hat" | no | Drum engine name or id; GET /v1/drum-engines lists them with their controls. Default `"kick"`. | | `param` | string | no | Comma-separated name=value controls in registry units (Hz, seconds, ratios; pct controls use 0..100). Kick: Tune=30..160 note, P.Depth=1..5 ratio, P.Decay=0.005..0.2 time, Decay=0.03..3 time, Click=0..100 percent, Drive=0..100 percent, Tone=150..16000 freq, Wave=0..100 percent; Snare: Tune=120..400 freq, Noise=0..100 percent, Decay=0.03..0.5 time, N.Decay=0.03..0.6 time, N.Tone=800..8000 freq, P.Depth=1..3 ratio, P.Decay=0.005..0.3 time, Drive=0..100 percent; HiHat: Tune=160..640 freq, Decay=0.02..1 time, Tone=2000..12000 freq, Metal=0..100 percent, Noise=0..100 percent; Clap: Freq=400..3500 freq, Spread=0.004..0.02 time, Decay=0.05..2 time, Reso=1..12 num, Drive=0..100 percent; Tom: Tune=80..400 note, P.Depth=1..3 ratio, Decay=0.05..2.5 time, Tone=120..12000 freq, Noise=0..100 percent, Drive=0..100 percent, P.Decay=0.01..0.8 time; FM: Tune=50..1000 note, Ratio=0.5..8 ratio, FM Amt=0..24 num, Decay=0.03..3 time, FM Decay=0..100 percent, F.Back=0..100 percent, Drive=0..100 percent; Cymbal: Tune=140..560 freq, Decay=0.2..4 time, Tone=3000..14000 freq, Metal=0..100 percent, Sizzle=0..100 percent; Cowbell: Tune=300..900 note, Decay=0.08..0.8 time, Ratio=1.2..1.8 ratio, Tone=700..9000 freq, Drive=0..100 percent; 808: Tune=27.5..220 note, P.Depth=0..36 st, P.Time=0.005..0.12 time, Decay=0.1..8 time, Saturate=0..100 percent, Click=0..100 percent, Tone=80..6000 freq; Shaker: Tune=2000..12000 freq, Color=0..100 percent, Onset=0.0005..0.05 time, Decay=0.02..0.6 time, Rattle=0..0.012 time, Tone=0..100 percent; Rim: Tune=200..2500 note, Ring=0..100 percent, Decay=0.015..0.15 time, Partial=1..2.7 ratio, Snap=0..100 percent, Drive=0..100 percent; Conga: Tune=75..700 note, Slap=1..2.5 ratio, Decay=0.08..0.7 time, Partial=1.4..2 ratio, Tone=300..9000 freq, Skin=0..100 percent, Drive=0..100 percent; Bell: Tune=200..1800 note, Ratio=1.4..7 ratio, FM Amt=0..10 num, Decay=0.2..4 time, Inharm=0..100 percent, Strike=0..100 percent, Tone=800..18000 freq; Pluck: Tune=60..1200 note, Sustain=0..100 percent, Damp=0..100 percent, Excite=0..100 percent, Bright=300..12000 freq, Drive=0..100 percent, Decay=0.3..6 time; Zap: Tune=40..2000 note, Sweep=-6..6 num, S.Time=0.02..1 time, Decay=0.03..1.5 time, Timbre=0..100 percent, Noise=0..100 percent, Drive=0..100 percent, Tone=200..14000 freq; Wave: Tune=40..2000 note, Position=0..100 percent, P.Env=1..4 ratio, Decay=0.03..1.5 time, Bright=300..14000 freq, Fold=0..100 percent, Drive=0..100 percent, Draw=0..100 percent; Chaos: Tune=40..6000 note, Chaos=0..100 percent, Decay=0.03..1.2 time, Tone=300..12000 freq, Drive=0..100 percent, Noise=0..100 percent; Stab: Tune=35..1000 note, Shape=0..100 percent, Width=0..100 percent, Chord=0..6 num, Detune=0..100 percent, Decay=0.05..3 time, Tone=200..16000 freq, Drive=0..100 percent; Acoustic Kick: Tune=35..120 note, Punch=1..4 ratio, Decay=0.12..1.8 time, Beater=0..100 percent, Shell=0..100 percent, Damp=0..100 percent, Tone=200..9000 freq, Drive=0..100 percent; Acoustic Snare: Tune=110..440 note, Depth=0..100 percent, Decay=0.08..1.2 time, Snap=0..100 percent, Wires=0..100 percent, Buzz=0.03..0.9 time, Tone=400..12000 freq, Drive=0..100 percent; Acoustic Cymbal: Size=180..900 freq, Strike=0..100 percent, Decay=0.4..8 time, Bell=0..100 percent, Sizzle=0..100 percent, Tone=200..6000 freq, Spread=0..100 percent, Drive=0..100 percent; Acoustic Hi-Hat: Size=260..1100 freq, Open=0..100 percent, Decay=0.08..4.5 time, Strike=0..100 percent, Chatter=0..100 percent, Sizzle=0..100 percent, Tone=1200..16000 freq, Drive=0..100 percent | | `duration` | number | no | Duration in seconds. From 0.05 to 30. Default `1`. | | `velocity` | number | no | Drum trigger velocity. From 0 to 1. Default `1`. | | `triggers` | string | no | Comma-separated trigger times in seconds. Default `"0"`. | | `sampleRate` | integer | no | Output sample rate. From 22050 to 48000. Default `48000`. | | `metadata` | map of string | no | Up to 20 string pairs stored with the job. At most 20 entries. | ## Example ```sh curl -sS "https://api.map.audio/v1/synth/drum" \ -H "Authorization: Bearer $MAP_API_KEY" \ -H "Map-Version: 2026-11-01" \ -H "Prefer: wait=30" \ -H "Content-Type: application/json" \ -d '{"engine":"808","param":"Tune=55,Decay=1.5","duration":2}' ``` ### Request: A two-second 808 tuned to 55 Hz ```json { "engine": "808", "param": "Tune=55,Decay=1.5", "duration": 2 } ``` ### 200: Finished ```json { "object": "job", "id": "job_01M6BPRFPCH9EBPY7B6JKM7CE1", "operation": "synthDrum", "status": "succeeded", "livemode": false, "sequence": 3, "progress": 1, "queuePosition": null, "createdAt": "2026-11-01T14:03:31.512Z", "startedAt": "2026-11-01T14:03:33.104Z", "finishedAt": "2026-11-01T14:03:41.877Z", "estimate": { "audioSeconds": 2, "renderMinutes": 0 }, "result": { "outputs": [ { "role": "master", "name": null, "cell": null, "file": "file_01M6BPRMNR7PYGFNA66BX2YJ8M", "sha256": "13d41d922519699fc14a7587130eceee7d0f149414350000578de1564866a0d4", "bytes": 576044, "format": "wav", "sampleRate": 48000, "durationSeconds": 2, "url": "https://api.map.audio/v1/download/file_01M6BPRMNR7PYGFNA66BX2YJ8M?expires=1793545422&signature=GQ2GkmPjqXuxxBSSM4NKBCY7OjU7w3YSeZBrCoxxtbY", "expiresAt": "2026-11-01T15:03:42.000Z" } ], "seed": null, "command": { "ok": true, "wavPath": "file_01M6BPRMNR7PYGFNA66BX2YJ8M", "sampleRate": 48000, "channels": 2, "durationSeconds": 2, "engine": "808" }, "provenance": { "object": "provenance", "id": "prov_01M6BPRVA8ZC7F7J737SQ0EPN2", "jobId": "job_01M6BPRFPCH9EBPY7B6JKM7CE1", "createdAt": "2026-11-01T14:03:41.877Z", "engine": { "product": "pam", "version": null, "runtime": "native-linux-x86_64", "image": "registry.cloudflare.com/c7c2e61448617e81ced650f444fb6787/pam-render@sha256:5c5ffe3fabc103e277280fbd65a08988d31361f00fe7857e36f603d67bcec42d" }, "seed": null, "presets": [], "packs": [], "userFiles": [], "inputs": [], "outputs": [ { "file": "file_01M6BPRMNR7PYGFNA66BX2YJ8M", "sha256": "13d41d922519699fc14a7587130eceee7d0f149414350000578de1564866a0d4" } ], "planner": null, "contracts": { "api": "2026-11-01", "pam.cli": 1 }, "aiModels": [], "audioByModel": false, "license": { "id": "lic_api_prototype_test", "commercialUse": false, "attribution": true }, "kid": "6c2f0a9d4b7e1358", "signature": "ed25519:LEVZHpOHj8BMGZgJh-_Y7SmKbqDlBDR8LqY-XelU6GYK8lntZqg3rRK4b3BH8cy25bK0iWzOXFXmkiGHEYue7A" } }, "error": null, "usage": { "renderMinutes": 0, "audioSeconds": 2, "computeMs": 6273 }, "metadata": {}, "urls": { "self": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1", "events": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/events", "cancel": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/cancel" } } ``` ### 202: Still running ```json { "object": "job", "id": "job_01M6BPRFPCH9EBPY7B6JKM7CE1", "operation": "synthDrum", "status": "running", "livemode": false, "sequence": 2, "progress": 0, "queuePosition": null, "createdAt": "2026-11-01T14:03:31.512Z", "startedAt": "2026-11-01T14:03:33.104Z", "finishedAt": null, "estimate": { "audioSeconds": 2, "renderMinutes": 0 }, "result": null, "error": null, "usage": null, "metadata": {}, "urls": { "self": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1", "events": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/events", "cancel": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/cancel" } } ``` ### 400: Invalid request ```json { "error": { "type": "invalid_request", "code": "invalid_request", "message": "duration must be at most 30; got 45.", "param": "duration", "retryable": false, "jobId": null, "docUrl": "https://map.audio/developers/music-api/errors#invalid_request", "requestId": "9a3f7c2e5b1d8f40-LHR" } } ``` ## Responses - `200`: The finished job: `result.outputs` link each file it wrote and `result.command` is the engine's own result. - `202`: The job, still running when `Prefer: wait` ran out; poll `urls.self`. - `400`: Invalid request - `default`: Any other error: `error.code` names it, `error.param` the field at fault, and `error.docUrl` its entry in the error catalogue. ## Errors - [`invalid_request`](https://map.audio/developers/music-api/errors#invalid_request) - [`unsupported_media_type`](https://map.audio/developers/music-api/errors#unsupported_media_type) - [`payload_too_large`](https://map.audio/developers/music-api/errors#payload_too_large) - [`terms_required`](https://map.audio/developers/music-api/errors#terms_required) - [`concurrency_limit`](https://map.audio/developers/music-api/errors#concurrency_limit) - [`idempotency_key_reused`](https://map.audio/developers/music-api/errors#idempotency_key_reused) - [`idempotency_in_flight`](https://map.audio/developers/music-api/errors#idempotency_in_flight) - [`queue_unavailable`](https://map.audio/developers/music-api/errors#queue_unavailable)