> For the complete documentation index, see [llms.txt](https://docs.muzaic.ai/muzaic-api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.muzaic.ai/muzaic-api-docs/context-to-soundtrack/context-to-soundtrack.md).
# Context to soundtrack
Turn a **design snapshot** (pages, text, images, timing) into one or more finished soundtrack MP3s — in a single API call.
Typical use: apps that already know the design layout (for example a Canva-style editor) and want music, optional sound effects, and optional voiceover without a video file.
**Base URL:** `https://m10.muzaic.ai`
You wait for one response. Longer designs can take a few minutes — use a high client timeout (for example **3 minutes**).
***
## Authentication
Every request needs your **API Secret Key** in the header:
```http
MuzaicAPI-Secret-Key: YOUR_SECRET_KEY
```
### How to get a Secret Key
1. Sign in at
2. Open your account / API keys section and copy the Secret Key
3. Use that value in the `MuzaicAPI-Secret-Key` header on every call
Keep the key private (server-side only). Do not put it in a public app or frontend.
Wrong or missing key → `401`.
***
## Check your balance — `GET /accountDetails`
Before you generate audio, you can check how many tokens you still have.
## Get account details
> Returns token balance and quotas for the API key.\
> Use this before generating audio to show remaining tokens in your UI.\
> Requires an API key (or Bearer token issued with API key context).\
> Also available as \`GET /accountDetails/{origin}\`.
```json
{"openapi":"3.0.0","info":{"title":"Muzaic Core API","version":"1.0.0"},"tags":[{"name":"Account","description":"Account information operations"}],"servers":[{"url":"https://m10.muzaic.ai","description":"Core API server"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"MuzaicAPI-Secret-Key","description":"Your Muzaic API Secret Key. Get it after signing in at https://adminpanel.muzaic.ai/\n(account / API keys). Required for normal Core API usage.\n"}}},"paths":{"/accountDetails":{"get":{"summary":"Get account details","description":"Returns token balance and quotas for the API key.\nUse this before generating audio to show remaining tokens in your UI.\nRequires an API key (or Bearer token issued with API key context).\nAlso available as `GET /accountDetails/{origin}`.\n","tags":["Account"],"responses":{"200":{"description":"Account details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"apiVersion":{"type":"string"},"secretKey":{"type":"string","description":"API key value for this account context"},"tokensAvailable":{"type":"number","description":"Tokens you can spend right now"},"currentBalance":{"type":"integer"},"resources":{"type":"object","additionalProperties":true},"tokens":{"type":"object","properties":{"daily":{"type":"object","properties":{"quota":{"type":"number","nullable":true},"remaining":{"type":"number","nullable":true}}},"weekly":{"type":"object","properties":{"quota":{"type":"number","nullable":true},"remaining":{"type":"number","nullable":true}}},"monthly":{"type":"object","properties":{"quota":{"type":"number","nullable":true},"remaining":{"type":"number","nullable":true}}}}}}}}}},"401":{"description":"Unauthorized"}}}}}}
```
***
## Generate audio — `POST /context-to-soundtrack`
Send a JSON body that describes the design (`design` + `pages`). Get back one or more soundtrack versions with MP3 URLs.
At least one layer must be on: **music**, **sfx**, or **voiceover**.
## Design snapshot to soundtrack
> Send a design snapshot (schemaVersion 2: \`design\` + \`pages\`) and get one or more finished soundtrack MP3s\
> in a single response. Same production path as \`/video-soundtrack\`, but audio-only from design context\
> (no video file required).\
> \
> \- \`versions\`: 1–4 takes\
> \- Billing: \`ceil(totalDurationSec) × versions\`, unless \`freeVersions: true\` (charge duration once)\
> \- At least one layer must be on: music, sfx, or voiceover\
> \- Keep JSON body under \~500 KB; client timeout \~180s recommended\
> \- Also available as \`POST /context-to-soundtrack/{origin}\`
```json
{"openapi":"3.0.0","info":{"title":"Muzaic Core API","version":"1.0.0"},"tags":[{"name":"Design","description":"Design snapshot to soundtrack (context-to-soundtrack)"}],"servers":[{"url":"https://m10.muzaic.ai","description":"Core API server"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"MuzaicAPI-Secret-Key","description":"Your Muzaic API Secret Key. Get it after signing in at https://adminpanel.muzaic.ai/\n(account / API keys). Required for normal Core API usage.\n"}}},"paths":{"/context-to-soundtrack":{"post":{"summary":"Design snapshot to soundtrack","description":"Send a design snapshot (schemaVersion 2: `design` + `pages`) and get one or more finished soundtrack MP3s\nin a single response. Same production path as `/video-soundtrack`, but audio-only from design context\n(no video file required).\n\n- `versions`: 1–4 takes\n- Billing: `ceil(totalDurationSec) × versions`, unless `freeVersions: true` (charge duration once)\n- At least one layer must be on: music, sfx, or voiceover\n- Keep JSON body under ~500 KB; client timeout ~180s recommended\n- Also available as `POST /context-to-soundtrack/{origin}`\n","tags":["Design"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["schemaVersion","design","pages"],"properties":{"schemaVersion":{"type":"integer","enum":[2]},"versions":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"Number of soundtrack takes to return"},"uniqueVersions":{"type":"boolean","default":true},"freeVersions":{"type":"boolean","description":"If true, bill design duration once (extra versions free)"},"quality":{"type":"string","enum":["normal","best","smart"],"default":"normal"},"name":{"type":"string"},"locale":{"type":"string"},"music":{"type":"boolean","description":"Enable music layer (short alias)"},"sfx":{"type":"boolean","description":"Enable SFX layer (short alias)"},"voiceover":{"type":"boolean","description":"Enable voiceover layer (short alias)"},"musicLayerEnabled":{"type":"boolean"},"sfxLayerEnabled":{"type":"boolean"},"voiceoverLayerEnabled":{"type":"boolean"},"sfxDensity":{"type":"string","enum":["none","sparse","moderate","dense"]},"sfxMode":{"type":"string","enum":["realistic","commercial","cinematic","designed"]},"musicTags":{"type":"array","items":{"type":"integer"}},"musicParams":{"type":"object","properties":{"intensity":{"type":"number"},"tempo":{"type":"number"},"rhythm":{"type":"number"},"tone":{"type":"number"},"variance":{"type":"number"}}},"motiveId":{"type":"integer"},"musicMode":{"type":"string","enum":["manual","auto"]},"voiceKind":{"type":"string","enum":["narration","screen_read"]},"voiceoverScript":{"type":"string"},"voiceoverMode":{"type":"string","enum":["dynamic","guided","manual"]},"voiceoverGender":{"type":"string","enum":["auto","female","male"]},"voiceoverEmotion":{"type":"string"},"voiceoverPace":{"type":"string","enum":["slow","measured","brisk","rapid"]},"voiceoverVoice":{"type":"string","description":"Provider voice id"},"voiceoverLanguage":{"type":"string"},"options":{"type":"object","properties":{"preferOneStyle":{"type":"boolean","default":true},"matchEachPage":{"type":"boolean","default":false},"matchBrandId":{"type":"boolean","default":false},"addMusic":{"type":"boolean"},"addSfx":{"type":"boolean"},"addVoiceover":{"type":"boolean"},"temperature":{"type":"number","minimum":1,"maximum":9,"default":5}}},"design":{"type":"object","required":["totalDurationSec","pageCount","colors"],"properties":{"title":{"type":"string"},"totalDurationSec":{"type":"number","exclusiveMinimum":0,"description":"Total design length in seconds (must be > 0)"},"pageCount":{"type":"integer","minimum":1},"colors":{"type":"array","items":{"type":"string"}},"brandColors":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"templates":{"type":"array","items":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"domain":{"type":"string"}}}}}},"pages":{"type":"array","minItems":1,"description":"Continuous page timeline (no gaps). Each page has timing + elements.","items":{"type":"object","required":["id","index","status","timing","elements","stats"],"properties":{"id":{"type":"string"},"index":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string","enum":["ok","unsupported","skipped"]},"isCurrent":{"type":"boolean"},"locked":{"type":"boolean"},"timing":{"type":"object","required":["startSec","durationSec","source"],"properties":{"startSec":{"type":"number"},"durationSec":{"type":"number"},"source":{"type":"string","enum":["canva","estimated"]}}},"elements":{"type":"array","items":{"type":"object","required":["kind","geometry"],"properties":{"kind":{"type":"string","enum":["text","image","video","icon","shape","embed","solid","group","other"]},"text":{"type":"string"},"role":{"type":"string","enum":["heading","subheading","body"]},"url":{"type":"string"},"urlStatus":{"type":"string","enum":["ok","restricted","error"]},"geometry":{"type":"object","properties":{"top":{"type":"number"},"left":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"rotation":{"type":"number"},"transparency":{"type":"number"},"locked":{"type":"boolean"},"zIndex":{"type":"integer"},"coverage":{"type":"number"}}}}}},"stats":{"type":"object","properties":{"textChars":{"type":"integer"},"images":{"type":"integer"},"videos":{"type":"integer"},"maxVideoSec":{"type":"number"}}}}}},"client":{"type":"object","properties":{"appVersion":{"type":"string"},"extractionMs":{"type":"number"},"truncated":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"One or more soundtrack versions","content":{"application/json":{"schema":{"type":"object","properties":{"apiVersion":{"type":"string"},"analysisId":{"type":"string","nullable":true},"mediaAttached":{"type":"integer","description":"How many design media files were attached for analysis"},"versionCount":{"type":"integer"},"tokensUsed":{"type":"number"},"soundtracks":{"type":"array","items":{"type":"object","properties":{"version":{"type":"integer"},"name":{"type":"string"},"mp3":{"type":"string","format":"uri","description":"Playable / downloadable MP3 URL"},"audioDuration":{"type":"number"},"soundtrackHash":{"type":"string"},"soundtrackIcon":{"type":"string","nullable":true},"regions":{"type":"array","items":{"type":"object","properties":{"time":{"type":"number"},"duration":{"type":"number"},"tags":{"type":"array","items":{"type":"integer"}},"motiveId":{"type":"integer","nullable":true},"params":{"type":"object","properties":{"intensity":{"type":"number"},"tempo":{"type":"number"},"rhythm":{"type":"number"},"tone":{"type":"number"},"variance":{"type":"number"}}}}}},"regionDetails":{"type":"array","items":{"type":"object"}},"hasVoiceover":{"type":"boolean"},"voiceKind":{"type":"string"},"voiceoverPreview":{"type":"string"},"voiceoverLanguage":{"type":"string"},"suggestExtendDesign":{"type":"boolean"},"designDurationSec":{"type":"number"}}}}}}}}},"400":{"description":"Invalid body (missing design/pages, duration ≤ 0, no layers)"},"401":{"description":"Unauthorized"},"500":{"description":"Soundtrack production failed"}}}}}}
```
***
## Suggested flow
1. Get your Secret Key from [adminpanel.muzaic.ai](https://adminpanel.muzaic.ai/).
2. Call `GET /accountDetails` if you want to show remaining tokens in your UI.
3. Build a schemaVersion **2** snapshot of the design.
4. Call `POST /context-to-soundtrack` with header `MuzaicAPI-Secret-Key`.
5. Play or download each `soundtracks[i].mp3`.