> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-audio-sdk-and-neural-dsp/the-sonic-sound-engine-api.md). # The Sonic Sound Engine API Canonical REST API for SONIC high-resolution audio analysis, stem decomposition, mastering, capability discovery and durable DSP operation tracking. **Status:** `Preview / Beta`\ **Canonical prefix:** `/api/v1`\ **Canonical namespace:** `/api/v1/sound` The SONIC Sound Engine API is the durable server-side audio-processing contract beneath SONIC AI Works. It provides stem separation, mastering, enhancement and analysis without exposing provider-specific APIs, credentials or lifecycle semantics to clients. > **Production rule** — DSP mutations are asynchronous durable operations. The HTTP request creates or recovers a SONIC `SoundOperation`, persists the idempotency record and dispatch job, then returns `202 Accepted`. Provider task IDs are correlation data only. ### Canonical endpoints ```http GET /api/v1/sound/capabilities POST /api/v1/sound/stems POST /api/v1/sound/master POST /api/v1/sound/enhance POST /api/v1/sound/analyze GET /api/v1/sound/operations/{operationId} GET /api/v1/sound/operations/{operationId}/result POST /api/v1/sound/operations/{operationId}/cancel ``` The earlier `/api/v1/sound-engine/*` draft namespace is not the canonical v1.2 public contract. ### Authentication and provider credentials Public Sound Engine requests use the normal SONIC authenticated authority boundary: ```http Authorization: Bearer ``` The public token proves SONIC application authority only. DSP provider credentials remain server-side and must never appear in browser bundles, React public environment variables, mobile bundles, wallet metadata, OpenAPI examples, public Postman environments or Git repositories. ``` Client ↓ SONIC API ↓ Sound Engine service ↓ server-side provider adapter ↓ DSP provider ``` ### Mandatory idempotency Every DSP mutation requires: ```http Idempotency-Key: ``` This applies to stem separation, mastering, enhancement, analysis and cancellation. The idempotency domain is: ``` tenant + workspace + endpoint + idempotency key + request hash ``` Same key + same request recovers the same durable operation. Same key + different request returns `409 IDEMPOTENCY_CONFLICT`. ### Durable operation lifecycle Status and stage are separate. Status is the coarse lifecycle; stage communicates current processing detail. ``` queued → dispatched → processing → completed ``` Terminal alternatives: ``` failed cancelled expired ``` Stages may include: ``` accepted uploading decoding analyzing stem_isolation mastering enhancing encoding persisting finished ``` A terminal operation is monotonic. A stale callback or polling result must never move `completed` back to `processing`, recreate output assets, or double-apply accounting effects. #### Accepted response ```json { "data": { "id": "sndop_01K...", "type": "stem_separation", "status": "queued", "stage": "accepted", "createdAt": "2026-09-04T12:40:00Z" }, "meta": { "requestId": "req_01K..." } } ``` ### Capability discovery High-resolution support is capability-driven rather than hard-coded. ```http GET /api/v1/sound/capabilities Authorization: Bearer ``` Example: ```json { "data": { "audio": { "sampleRates": [44100, 48000, 96000], "bitDepths": [16, 24], "formats": ["wav", "flac"], "maximumChannels": 2 }, "features": { "stemSeparation": { "supported": true, "maximumStems": 6 }, "mastering": { "supported": true }, "enhancement": { "supported": true }, "analysis": { "supported": true } } }, "meta": { "requestId": "req_01K..." } } ``` Clients must discover `96000` Hz and `24`-bit support here. Capability resolution may vary by environment, active provider, product tier and deployment state. ### Stem separation ```http POST /api/v1/sound/stems Authorization: Bearer Idempotency-Key: stem-project-348-v1 Content-Type: application/json ``` ```json { "input": { "assetId": "ast_01K..." }, "stems": ["vocals", "drums", "bass", "other"], "output": { "format": "wav", "sampleRate": 96000, "bitDepth": 24 } } ``` The request is rejected with `422` when the active capability snapshot does not support the requested stem count or output profile. ### Mastering ```http POST /api/v1/sound/master ``` Initial mastering profiles are `balanced`, `streaming`, `transparent` and `loud`. The request may include a supported `targetLufs` and output profile. ### Enhancement ```http POST /api/v1/sound/enhance ``` Initial enhancement vocabulary includes `denoise`, `declick`, `dehum`, `clarity`, `stereo_width` and `voice_cleanup`. Unsupported features are rejected rather than silently ignored. ### Analysis ```http POST /api/v1/sound/analyze ``` Analysis may request verified fields such as duration, loudness, peak, BPM, key, sample rate, bit depth and channel count. Unsupported or unverified fields must not be fabricated. ### Operation retrieval ```http GET /api/v1/sound/operations/sndop_01K... ``` ```json { "data": { "id": "sndop_01K...", "type": "stem_separation", "status": "processing", "stage": "stem_isolation", "progress": { "percent": 64 }, "input": { "assetId": "ast_01K..." }, "createdAt": "2026-09-04T12:40:00Z", "startedAt": "2026-09-04T12:40:02Z" }, "meta": { "requestId": "req_01K..." } } ``` ### Result retrieval Result data has its own endpoint so operation polling does not require repeatedly transferring large normalized output metadata. ```http GET /api/v1/sound/operations/sndop_01K.../result ``` Completed example: ```json { "data": { "id": "sndop_01K...", "status": "completed", "stage": "finished", "outputs": [ { "type": "stem", "stem": "vocals", "assetId": "ast_vocals_01K...", "format": "wav", "sampleRate": 96000, "bitDepth": 24 } ] }, "meta": { "requestId": "req_01K..." } } ``` Until the operation is complete, the result endpoint returns a normalized result-not-ready conflict rather than synthetic output. ### Cancellation ```http POST /api/v1/sound/operations/sndop_01K.../cancel Authorization: Bearer Idempotency-Key: cancel-sndop-01K-v1 ``` Cancellation is a mutation and uses the same idempotency rules. Completed, failed or expired operations cannot be rolled backward by a cancellation request. ### Provider interface Public contracts never expose provider payloads directly. Adapters implement a normalized interface: ```ts interface SoundEngineProvider { getCapabilities(): Promise; separateStems(input: StemRequest): Promise; master(input: MasterRequest): Promise; enhance(input: EnhanceRequest): Promise; analyze(input: AnalyzeRequest): Promise; getOperation(id: string): Promise; cancelOperation(id: string): Promise; } ``` ### Callback + polling convergence Callbacks and polling enter the same normalization and monotonic merge path: ``` provider callback ─┐ ├─► normalizeProviderState() provider polling ──┘ ↓ mergeSoundState() ↓ SoundOperation ↓ normalize output assets ↓ sound.operation.completed ``` The merge path protects against duplicate callbacks, out-of-order events, callback/poll races, duplicate output assets, state regression and double accounting. ### Persistence model The durable business identity is `SoundOperation`. Provider attempts are separate records so provider failover does not change the public operation ID. ``` SoundOperation ├── scope: tenant / workspace / project / createdBy ├── type / status / stage / progress ├── inputSnapshot ├── outputSpecSnapshot ├── capabilitySnapshot ├── provider / providerTaskId ├── idempotencyKey / requestHash └── lifecycle timestamps SoundOperationAttempt ├── operationId ├── provider / providerTaskId ├── attempt ├── requestSnapshot / responseSnapshot └── dispatch/completion state ``` Output assets and provider events use separate durable tables with uniqueness constraints to prevent duplicate materialization. ### Repository boundaries ``` packages/sound-engine/ ├── domain/ ├── providers/ ├── capabilities/ ├── operations/ ├── callbacks/ ├── normalization/ ├── persistence/ └── http/ ``` The HTTP layer owns authentication, validation and response normalization. Workers own provider dispatch and polling. Internal provider callbacks are not part of the public `/api/v1` surface. ### OpenAPI source of truth ``` api/swagger/sonic.yaml ``` The same specification drives Swagger, GitBook, Postman, contract tests, SDK generation and backend validation. A contract validation failure blocks merge. The canonical Sound Engine contract is OpenAPI `1.2.0` under the `Sound Engine` tag. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-audio-sdk-and-neural-dsp/the-sonic-sound-engine-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.