Skip to API documentation
OrynosMusic
Temporary Free phase · 5,000 weekly credits after verification

All modules and models are included for verified accounts. Each render uses the displayed model credit cost. Purchased credits remain in your account; new purchases are paused.

Sign in and verify your email to activate Free access. Sign in · Create account

OrynosMusic API Documentation

Analyze tracks, master audio, and mix stem sessions from your own application.

# Keep the key on your server
export ORYNOSMUSIC_API_KEY="YOUR_API_KEY"

curl --fail-with-body \
  -H "X-API-Key: $ORYNOSMUSIC_API_KEY" \
  -F "file=@track.wav" \
  https://orynosmusic.com/api/analyze
https://orynosmusic.com
On this page

Your first request.

Three steps are enough. Use the API from a trusted backend, CLI, worker, or desktop application.

Get an API key

Sign in with a verified account and open Settings to create your personal API key. Copy the plaintext when it appears: it is shown once. Settings then shows its public prefix and creation/last-use times, with Rotate and Revoke controls.

Store it securely

Put the key in a server-side secret or an environment variable such as ORYNOSMUSIC_API_KEY.

Send the header

Add X-API-Key or Authorization: Bearer to every integration request. Never append a key to a URL or query string.

Do not call OrynosMusic directly from public browser JavaScript.

The API intentionally has no cross-origin browser access. A frontend would expose your long-lived key to every visitor. Call OrynosMusic from your own backend and return only the result your app needs.

One key. Every request.

Your personal key authenticates the verified account that created it. The server checks its current account eligibility and revocation state on every request.

API-key header Recommended
X-API-Key: YOUR_API_KEY

The clearest option for OrynosMusic integrations.

Bearer authorization Supported
Authorization: Bearer YOUR_API_KEY

Useful when your HTTP client already supports bearer tokens.

Jobs and credit charges belong to your account.

Use an active key for the owning account when polling, previewing, and downloading. Rotating the key invalidates the old secret immediately; its replacement can still read that account's unexpired jobs. Other accounts receive 404. Ordinary website logout keeps the integration key active. Password changes/resets and a confirmed email change revoke it; banned, deleted or unverified accounts are blocked.

Personal keys have a limited scope.

They support audio analysis/rendering, model catalogs, credit balances, account-owned jobs, current render history, render feedback, your own custom DSP profiles and reading your saved workflow library. They do not authorize account changes, key management, billing, administration, Discord account connections, community posting or moderation. Create, rotate and revoke keys through the verified first-party Settings session; header keys cannot manage themselves.

Legacy installation keys can analyze audio. Rendering with a legacy key additionally needs a real verified account cookie to own the job and credit charge. An installation access grant alone is not an account.

Mastering is asynchronous.

Standard costs per track during the temporary Free phase are 0 credits for Premier, 12 for Galaxy, 20 for Sun, 35 for Orynos Whitehole V11.0, 40 for Aurora and 60 for Orynos Blackhole V11.0. Verified accounts receive 5,000 weekly credits. Send ai_model as premier, galaxy, sun, whitehole, aurora or blackhole. The personal API defaults to Premier when no model is specified. Check /api/credits for current access and prices.

render_mode uses normal (1×), power (2×), ultra (5×) or max (10×). Premier supports Standard only. Mastering costs apply per track; mixing costs one generation. Credits are reserved at submission and refunded when rendering fails. Every mode runs one final processing chain.

Orynos Blackhole V11.0 is the flagship. It supports Aurora’s 15 aurora_* controls, spatial processing and ADM delivery. The model catalog describes the controls and their defaults.

Submit the audio once, poll a lightweight job endpoint, then download before the result expires.

OPTIONAL · POSTAnalyzeMeasure the source and inspect the mastering recommendation.
POSTSubmit masterUpload track(s), settings, and an optional reference.
GET · ~2 SECPoll jobWait for completed or stop on error.
GET · 300 SECDownloadSave the advertised audio format before its RAM result expires.
BASE_URL="https://orynosmusic.com"
API_KEY="$ORYNOSMUSIC_API_KEY"

# 1. Submit the mastering job
curl --fail-with-body -H "X-API-Key: $API_KEY" \
  -F "file=@track.wav" \
  -F 'settings={"preset":"AI","ai_model":"premier","target_lufs":-14,"ceiling":-1,"bitdepth":24}' \
  "$BASE_URL/api/master"
# => {"success":true,"job_id":"JOB_ID"}

# 2. Poll approximately every two seconds
curl --fail-with-body -H "X-API-Key: $API_KEY" \
  "$BASE_URL/api/job/JOB_ID"

# 3. Download immediately after completion
curl --fail-with-body -H "X-API-Key: $API_KEY" \
  -OJ "$BASE_URL/api/download/JOB_ID"

The four calls you will use most.

These are the stable, developer-facing processing operations. All multipart examples let your HTTP client generate the boundary automatically.

POST

Analyze a track

/api/analyze

Runs a synchronous technical analysis and adds recommended mastering targets. Use it to explain what OrynosMusic hears before you submit a master.

FieldTypeRequiredDescription
fileAudio fileYesOne file, maximum 250 MiB. Supported: .aac, .aif, .aiff, .caf, .flac, .m4a, .mp3, .ogg, .wav.
20 requests / minuteapplication/jsonSynchronous
POST

Submit a master

/api/master

Queues an asynchronous mastering job. A successful submission returns a job_id; it does not contain the rendered audio yet. Check HTTP success and the JSON response before starting your poll loop.

FieldTypeRequiredDescription
fileAudio file, repeatedYes1-24 tracks. Combined audio and reference maximum 250 MiB.
settingsJSON stringNoPreset, loudness, ceiling, export depth, tone, and advanced modules. Maximum 65,536 characters.
reference_fileAudio fileNoOptional tonal/loudness reference in a supported format.
8 submissions / minuteAccount-owned concurrency limitsQueue capacity 25
GET

Poll and collect

/api/job/<job_id> · /api/preview/<job_id> · /api/download/<job_id>

Poll mastering or mixing status about every two seconds. When status becomes completed, download immediately. Read result.download_options, expires_at and retention_seconds. Albums and multi-song mastering batches return delivery_mode: "album" with a fixed 3,600-second window from completion. Other API renders keep their 300-second window. Polling and downloading do not extend either window. Audio is held in RAM, so a process restart removes it.

?format=wav, ?format=flac or ?format=mp3 selects an advertised format on /api/download/JOB_ID. WAV/FLAC support 192 kHz output; MP3 is unavailable at 192 kHz. Other high-rate MP3 exports use compatible 44.1/48 kHz at 320 kbps. Packaged masters may download as ZIP.

StatusMeaningNext action
queuedWaiting for a worker and sufficient render RAM.Show queue_position when present and poll again. Do not upload or submit again.
processingAudio render is running.Use progress for UI; poll again.
completedResult is ready.Download immediately.
errorThe render failed.Show the error and stop polling.
Owning account requiredWAV / FLAC / MP3 / ZIP404 hides ownership
POST

Mix a stem session

/api/mix

Send X-Orynos-Async: 1 to queue a mix and receive HTTP 202 with job_id. Poll /api/job/JOB_ID, then download from /api/download/JOB_ID. Repeated stems parts map to zero-based routing[].index. Without the async header, the request waits and returns a WAV directly. Upload, queue, render and result-expiry limits are separate.

FieldTypeRequiredDescription
stemsWAV, repeatedYes1-96 files; total maximum 900 MiB; each up to 12 minutes.
settingsJSON stringYesStyle, per-stem routing, buses, reference matching, and render output.
referenceWAVNoUsed when reference_match is true.
mix-request.sh
curl --fail-with-body \
  -H "X-API-Key: $ORYNOSMUSIC_API_KEY" \
  -H "X-Orynos-Async: 1" \
  -F "stems=@vocal.wav" \
  -F "stems=@beat.wav" \
  -F 'settings={"ai_model":"premier","render_mode":"normal","style":{"name":"clean","headroom_db":-6,"use_true_peak_limiter":true},"routing":[{"index":0,"category":"vocals"},{"index":1,"category":"music"}],"render":{"output_sr":48000,"bitdepth":24}}' \
  "https://orynosmusic.com/api/mix"

curl --fail-with-body -H "X-API-Key: $ORYNOSMUSIC_API_KEY" \
  "https://orynosmusic.com/api/job/JOB_ID"

curl --fail-with-body -H "X-API-Key: $ORYNOSMUSIC_API_KEY" \
  -o orynosmusic_mix.wav "https://orynosmusic.com/api/download/JOB_ID?format=wav"
4 renders / 5 minutes202 + job_idAsynchronousMix v8.0 Source-aware Vocal Balancing

Every API operation.

Search by path, action, authentication type, or feature. Open any operation for its request, response, and common errors.

96 operations
Core audio API is the supported server-to-server surface. Account, privacy, community, pack, and artist-page routes power the OrynosMusic website and are documented for completeness; treat their raw schemas as website-internal and subject to change.

Access & privacy

API-key access and the website's optional-advertising consent state.

Website integration
GET /api/access/status Check API access

Reports API-access configuration and whether the current request is authorized, without revealing a credential.

PublicStandard
RequestNo request body.
Success response{"configured": true, "authorized": false}
Errors / notesNo endpoint-specific errors.
POST /api/access/verify Create a browser key session

Validates a legacy installation key for the first-party access screen. Personal account keys are created in Settings and used in request headers. A browser installation grant does not create a verified account or a credit owner.

PublicFailed-attempt protection
RequestJSON or form: {"api_key":"YOUR_API_KEY","next":"/mastering"}. next must be a local path.
Success response{"ok": true, "next": "/mastering"}
Errors / notes401 INVALID_API_KEY · 429 RATE_LIMITED · 503 API_KEYS_NOT_CONFIGURED
GET /api/privacy/consent Read privacy choice

Returns the advertising-consent state for the current browser/session.

Website session; personal API keys are outside this scopeStandard
RequestNo request body.
Success response{"ok":true,"available":true,"version":"…","decided":true,"advertising":false,"decided_at":0,"receipt_id":"…"}
Errors / notes401 when neither an API key nor first-party website session is present.
POST /api/privacy/consent Update privacy choice

Stores an explicit optional-advertising choice and returns the resulting consent record.

Website session; personal API keys are outside this scopeStandard
RequestJSON: {"advertising": false}
Success response{"ok":true,"decided":true,"advertising":false,"receipt_id":"…"}
Errors / notes400 when advertising is not a boolean · 403 for an invalid cookie-session origin.

Audio engines

Analyze, master, and mix audio with the OrynosMusic processing engines.

Core developer API
POST /api/analyze Analyze a track

Synchronously measures loudness, dynamics, spectrum, stereo image, and returns a mastering recommendation.

Personal account API key or website session; legacy installation keys also supported20 / minute
Requestmultipart/form-data: file (one supported audio file, maximum 250 MiB).
Success responseJSON analysis object including ai_recommendation and feature_recommendations (measured feature suggestions and reasons, based on the first 30 seconds).
Errors / notes400 NO_FILE or INVALID_FILE_TYPE · 413 INVALID_FILE_SIZE/PAYLOAD_TOO_LARGE · 500 ANALYSIS_ERROR
POST /api/master Submit mastering job

Queues mastering against the verified account that owns the personal key. During the temporary Free phase, ordinary verified accounts receive 5,000 weekly credits and all available models/full modules. Normal credit costs, technical restrictions and account quotas still apply; catalogs report current eligibility.

Personal account API key or verified website account8 / minute
Requestmultipart/form-data: file (repeat, up to 24 with full access), settings (JSON string), optional reference_file. Combined audio maximum 250 MiB. settings.ai_model: premier (0 credits), galaxy (12), sun (20), whitehole (35, Orynos Whitehole V11.0 Premium), aurora (40), blackhole (60, Orynos Blackhole V11.0 Flagship Premium), per track in normal mode. render_mode: normal (1×), power (2×), ultra (5×) or max (10×). Premier supports normal only. Aurora costs 40/80/200/400 credits and Blackhole costs 60/120/300/600 credits. Both support the same 15 boolean aurora_* controls and optional restoration. Discover their defaults in /api/credits models[].exclusive_features. Optional restoration is off by default. Each mode uses one final mastering chain; powermaster=true aliases power. Personal API requests without ai_model use Premier. Moon and Classic are retired. Choose a current model for new renders. Failed renders refund their original reservation. Spatial headphone delivery is available with Sun, Galaxy, Aurora and Blackhole: binaural_spatial_master (boolean), adm_export (boolean, default true), spatial_amount (0-1, default 0.70), spatial_profile (studio, wide or immersive; default immersive), spatial_width (0-1, default 0.65), spatial_height (0-1, default 0.55), spatial_sample_rate (48000 or 96000; default 48000). Selectable booleans spatial_early_reflections, spatial_diffusion, spatial_center_lock, spatial_bass_anchor and spatial_transient_guard default true. The ZIP retains the regular stereo master and adds a synthetic binaural scene, its processing manifest and optional generic ADM/BW64 interchange. It is not source separation or a certified proprietary immersive format. The spatial preview uses the same owner-bound five-minute completion window.
Success response{"success": true, "job_id": "b6f…"}
Errors / notes400 validation error · 401 missing account/key · 402 INSUFFICIENT_CREDITS · 403 verification/eligibility · 429 CONCURRENCY_LIMIT · 503 QUEUE_FULL/QUEUE_CAPACITY · 413 PAYLOAD_TOO_LARGE/RENDER_TOO_LARGE
POST /api/mix Render a stem mix

Queues a WAV-stem mix. Send X-Orynos-Async: 1 for HTTP 202 with a job identifier, then poll /api/job/<job_id> and download the completed result. Without this header the request waits and returns the WAV directly. Full access supports 96 stems/900 MiB/12 minutes per stem, reference matching, sequence automation and hi-res output; paid-mode Free limits are 16/500 MiB/8 minutes.

Personal account API key or verified website account4 / 5 minutes
Requestmultipart/form-data: stems (repeat), settings (required JSON string), optional reference. WAV inputs only. settings.routing rows use index and category (drums, bass, vocals, music, fx); vocal_role is lead, double, double_left or double_right. Doubles stay on the vocals bus and use the measured support-vocal balance in automatic processing. double creates a stereo double from a mono source; double_left/right default to pan -0.75/+0.75 unless an explicit pan overrides it. Omitting vocal_role preserves filename-based inference. Optional vocal-only pitch correction uses autotune_enabled (boolean, default false), autotune_key (0-11, C=0), autotune_scale (chromatic, major, minor), autotune_amount (0-1, default 0.5) and autotune_speed_ms (20-250, default 80). Use a separate monophonic vocal take; uncertain/unvoiced material is preserved. settings.ai_model and render_mode follow mastering model/mode costs; one completed mix is one generation. render.output_sr supports source/null, 44100, 48000, 88200, 96000, 176400 or 192000; render.bitdepth is 16 or 24. recommendations_only=true returns measured suggestions without rendering or spending credits.
Success response{"job_id":"UUID"} (HTTP 202 with X-Orynos-Async: 1); otherwise WAV with X-Mix-* headers. recommendations_only returns JSON with feature_recommendations instead.
Errors / notes400 validation error · 402 INSUFFICIENT_CREDITS · 403 verification/eligibility · 413 PAYLOAD_TOO_LARGE · 429 CONCURRENCY_LIMIT · 503 QUEUE_FULL/QUEUE_CAPACITY
POST /api/premium/validate Validate supporter access

Checks a legacy donator key or the live supporter rank of the signed-in account.

Website session; personal API keys are outside this scopeStandard
RequestJSON: {"donator_key":"optional-legacy-key"}
Success response{"ok": true}
Errors / notes500 only if validation cannot be completed.

Mastering jobs & files

Poll account-owned asynchronous mastering or mixing jobs and collect temporary completed audio.

Core developer API
GET /api/job/<job_id> Read job status

Returns queued, processing, completed, or error state. Poll approximately every two seconds. Queued responses include queue_position; jobs wait for render resources without another upload. Album and multi-song results use delivery_mode=album and 3600 seconds from completion; other API results keep 300 seconds.

Personal key for the owning account or owning website sessionStandard
Requestjob_id returned by POST /api/master or POST /api/mix. Personal-key ownership is account-bound: a newly rotated key for the same account can read a still-valid job.
Success response{"status":"completed","job_id":"UUID","progress":100,"result":{"output_filename":"output.wav","download_formats":["wav","mp3","flac"],"download_options":[],"completed_at":0,"expires_at":300,"retention_seconds":300}}
Errors / notes404 when the job is missing, expired, or owned by another key/session.
GET /api/preview/<job_id> Stream a preview

Streams the first completed master as inline WAV audio for playback.

Personal key for the owning account or owning website sessionStandard
RequestPath parameter: completed job_id.
Success responseBinary audio/wav (inline).
Errors / notes404 when unavailable, expired, or not owned by the caller.
GET /api/preview/<job_id>/<kind> Stream a Studio monitor

Streams an available Premium Studio monitor render: mono, phone, small_speaker, or loudness-matched delta.

Personal key for the owning account or owning website sessionStandard
RequestPath parameters: completed job_id and an allowlisted monitor kind returned by the job result.
Success responseBinary audio/wav (inline).
Errors / notes404 when the variant is unavailable, expired, invalid, or not owned by the caller.
GET /api/download/<job_id> Download a master

Downloads completed mastering or mixing output as WAV, FLAC or MP3 when advertised in download_options. Packaged/multi-track masters use ZIP. The default completed mix is WAV; 192 kHz output supports WAV/FLAC, not MP3.

Personal key for the owning account or owning website sessionStandard
RequestCompleted job_id; optional ?format=wav, flac or mp3. Use the result download_options for availability. Higher supported MP3 sources are resampled to compatible 44.1/48 kHz; MP3 uses 320 kbps. Download within 300 seconds after completion, before expires_at.
Success responseaudio/wav, audio/flac, audio/mpeg or application/zip attachment; private, no-store.
Errors / notes404 unavailable, expired or not owned · 400 unsupported format · 429 EXPORT_BUSY / EXPORT_MEMORY_BUSY
GET /api/master/archive List archived renders

Lists only the current account’s available completed renders in RAM. This is a temporary result list, not persistent seven-day audio storage. Results expire 300 seconds after completion and are lost on server restart.

Personal key for the owning account or eligible website sessionStandard
RequestNo request body.
Success response{"ok":true,"items":[{"id":"UUID","filename":"output.wav","size_bytes":123,"created_at":0,"expires_at":300}],"retention_seconds":300,"storage":"RAM"}
Errors / notes401 signed out · 403 Premium required.
GET /api/master/archive/<record_id>/download Download archived render

Downloads one current RAM result belonging to the account. Its original 300-second expiry still applies; listing or downloading does not extend it.

Personal key for the owning account or eligible website sessionStandard
RequestNo request body.
Success responseBinary ZIP or WAV attachment.
Errors / notes401 signed out · 403 Premium required · 404 unknown or expired.
DELETE /api/master/archive/<record_id> Delete archived render

Removes one archived render and its stored file.

Website sessionStandard
RequestNo request body.
Success response{"ok": true}
Errors / notes401 signed out · 404 unknown record.

Accounts

Website-account sessions used by community and publishing features.

Website integration
GET /api/account/api-key Read personal API-key metadata

Settings reads the active key’s public metadata only. A personal key cannot call its own management endpoints; no stored plaintext secret is returned.

Verified website account cookie + trusted same-origin requestStandard
RequestNo body. Use the first-party Settings page; personal Authorization/X-API-Key credentials are rejected.
Success response{"key":{"id":"public-id","prefix":"ory_api_public-id-prefix","created_at":0,"last_used_at":null},"verified":true} or {"key":null,"verified":true}
Errors / notes401 signed out · 403 unverified, banned or invalid website origin
POST /api/account/api-key Create your personal API key

Creates one active personal key. The plaintext api_key is returned once; copy it into your secret store. Settings subsequently shows only the public prefix and timestamps.

Verified website account cookie + trusted same-origin requestStandard
RequestNo key in headers or URL. Create through Settings while signed in with a verified account.
Success response{"key":{"id":"public-id","prefix":"ory_api_public-id-prefix","created_at":0,"last_used_at":null},"verified":true,"api_key":"YOUR_PERSONAL_API_KEY"}
Errors / notes401 signed out · 403 unverified, banned or invalid origin · 409 API_KEY_EXISTS
POST /api/account/api-key/rotate Rotate your personal API key

Immediately invalidates the old key and reveals a replacement once. Update your integration’s secret store. The new key retains access to still-valid jobs owned by the same account.

Verified website account cookie + trusted same-origin requestStandard
RequestRotate through the first-party Settings page. Never pass the old secret in a URL.
Success response{"key":{"id":"new-public-id","prefix":"ory_api_public-id-prefix","created_at":0,"last_used_at":null},"verified":true,"api_key":"YOUR_NEW_PERSONAL_API_KEY"}
Errors / notes401 signed out · 403 unverified, banned or invalid origin
DELETE /api/account/api-key Revoke your personal API key

Immediately revokes the account’s active key. Repeating deletion is safe and returns HTTP 200. Ordinary website logout does not revoke an integration key; password changes/resets and confirmed email changes do.

Verified website account cookie + trusted same-origin requestStandard
RequestRevoke through Settings. Banned, deleted or unverified accounts are blocked on every key-authenticated request.
Success responseHTTP 200 after revocation; no plaintext key.
Errors / notes401 signed out · 403 unverified, banned or invalid origin
GET /api/auth/me Read current account

Returns the account attached to the current cookie session, including canonical plan and Premium status.

Website session; personal API keys are outside this scopeStandard
RequestNo request body. Preserve the account cookie for external account workflows.
Success response{"ok":true,"user":{"id":"…","username":"artist","email":"…","premium":true,"plan":"legacy_supporter"}}
Errors / notesuser is null when no account is signed in.
POST /api/auth/login Sign in

Validates credentials and establishes a persistent signed account cookie.

Website session; personal API keys are outside this scope30 / 5 minutes
RequestJSON: {"username":"artist","password":"at-least-8-chars"}
Success response{"ok":true,"user":{"id":"…","username":"artist","is_donator":false}}
Errors / notes400 missing fields · 401 invalid credentials.
POST /api/auth/register Create account

Creates a website account and signs it in.

Website session; personal API keys are outside this scope10 / hour
RequestJSON: {"username":"artist","email":"you@example.com","password":"at-least-8-chars"}. Username: 3-32 letters, numbers, _, -, or . A valid email is required and is confirmed via a link.
Success response{"ok":true,"user":{"id":"…","username":"artist","email":"you@example.com","email_verified":false},"verification_email_sent":true}
Errors / notes400 invalid username/password/email · 409 username or email already exists.
POST /api/auth/logout Sign out

Revokes existing account sessions while keeping an independent browser API-key grant intact.

Website session; personal API keys are outside this scopeStandard
RequestNo request body.
Success response{"ok": true}
Errors / notesNo endpoint-specific errors.
POST /api/auth/request-verification Resend email confirmation

Sends a fresh 24-hour email-confirmation link to the account's stored address.

Website session5 / hour
RequestNo request body.
Success response{"ok":true,"verification_email_sent":true}
Errors / notes400 no email on the account · 401 signed out.
POST /api/auth/set-email Set account email

Confirms your current password and stores the new address as pending. Your existing verified recovery address remains active until the new inbox confirms its one-use link. Confirmation revokes older signed-in sessions.

Website session6 / hour
RequestJSON: {"email":"new@example.com","current_password":"current-password"}
Success response{"ok":true,"email":"current@example.com","email_verified":true,"pending_email":"new@example.com","verification_email_sent":true}
Errors / notes400 invalid email or REAUTH_REQUIRED · 401 signed out or REAUTH_FAILED · 409 address already linked · 429 RATE_LIMITED.
POST /api/auth/forgot-password Request password reset

Sends a one-hour reset link only to a confirmed account address. Pending and unverified addresses cannot reset passwords. The response is deliberately identical for unknown emails.

Website session; personal API keys are outside this scope6 / hour
RequestJSON: {"email":"artist@example.com"}
Success response{"ok":true,"message":"If the email is registered, we have sent a reset link."}
Errors / notes400 missing email · 429 RATE_LIMITED.
POST /api/auth/reset-password Reset password

Consumes a one-time password-reset token and revokes older account sessions.

Website session; personal API keys are outside this scope10 / hour
RequestJSON: {"token":"one-time-token","password":"new-password"}
Success response{"ok": true}
Errors / notes400 invalid/expired token or password shorter than 8 characters.
POST /api/auth/change-password Change password

Checks the current password, stores a new password, and revokes other signed-in browser sessions.

Account cookie required6 / hour
RequestJSON: {"current_password":"current-password","new_password":"new-password"}
Success response{"ok":true,"message":"Password updated. Other signed-in browsers have been signed out."}
Errors / notes400 invalid new password · 401 signed out or current password incorrect.
POST /api/auth/profile Update profile

Updates public supporter consent. Email changes use the same password-confirmed pending workflow as set-email; the recovery address cannot be cleared.

Account cookie requiredStandard
RequestJSON: {"public_supporter":true}, or {"email":"new@example.com","current_password":"current-password"}.
Success response{"ok":true,"user":{"id":"…","username":"artist","email":"current@example.com","email_verified":true,"pending_email":"new@example.com","is_donator":false}}
Errors / notes400 invalid consent/email or REAUTH_REQUIRED · 401 login required or REAUTH_FAILED · 409 email already in use · 429 RATE_LIMITED.
GET /api/donators List supporters

Returns up to 500 grandfathered supporter usernames that explicitly opted into public recognition.

Website session; personal API keys are outside this scopeStandard
RequestNo request body.
Success response{"donators":["producer_one","producer_two"]}
Errors / notesNo endpoint-specific errors.

Premium & billing

Read the Premium catalog, manage account workspaces, and start authenticated Paddle billing flows.

Website integration
GET /api/premium/catalog Read Premium catalog

Returns the canonical viewer plan and the current Premium extensions for each product area.

Personal account API key or website sessionStandard
RequestNo request body.
Success response{"viewer":{"premium":false,"plan":"free"},"groups":{"mastering":[…]},"billing_ready":false}
Errors / notesNo endpoint-specific errors.
GET /api/premium/library/<area> Read Premium workspace

Lists the signed-in account's small, structured workspace records for mastering, mixing, packs, community, or artist pages.

Personal account API key or eligible website accountStandard
RequestPath parameter: area.
Success response{"ok":true,"area":"mastering","items":[]}
Errors / notes401 login required · 403 ENTITLEMENT_REQUIRED · 404 unknown workspace.
POST /api/premium/library/<area> Create Premium workspace item

Stores a named, size-limited settings or planning record for one library-mode Premium feature.

Premium account cookie requiredStandard
RequestJSON: {"feature_code":"master.cloud_presets","title":"Warm release","payload":{"notes":"…"}}
Success response{"ok":true,"id":"…"}
Errors / notes400 invalid feature/name · 403 ENTITLEMENT_REQUIRED · 409 workspace limit · 413 item too large.
DELETE /api/premium/library/<area>/<item_id> Delete Premium workspace item

Deletes one account-owned Premium workspace record.

Account owner cookie requiredStandard
RequestPath parameters: area and item_id.
Success response{"ok":true}
Errors / notes401 login required · 404 item not found.
GET /api/billing/status Read billing status

Returns canonical Free/Premium state and whether checkout is fully configured.

Website session; personal API keys are outside this scopeStandard
RequestNo request body.
Success response{"ok":true,"viewer":{"premium":false},"checkout_ready":false}
Errors / notesNo endpoint-specific errors.
GET /api/billing/catalog Read verified billing catalog

Returns the server-verified Paddle product plus monthly and annual prices without exposing credentials.

Website session; personal API keys are outside this scopeStandard
RequestNo request body.
Success response{"ok":true,"verified":true,"product":{"id":"pro_…"},"prices":{"monthly":{"id":"pri_…","display":"€11.99/month"}}}
Errors / notes503 BILLING_NOT_READY or CATALOG_UNAVAILABLE.
POST /api/billing/checkout-intent Create checkout intent

Verifies the Paddle catalog, then creates a 60-minute account-bound intent for an allowlisted recurring price. It does not grant Premium.

Signed-in Free account requiredStandard
RequestJSON: {"price_id":"pri_…"}
Success response{"ok":true,"environment":"sandbox","price_id":"pri_…","checkout_intent":"…","client_token":"test_…","customer_email":null}
Errors / notes400 unknown price · 401 login required · 409 ALREADY_PREMIUM · 503 BILLING_NOT_READY or CATALOG_UNAVAILABLE.
POST /api/billing/reconcile Recover billing state

Safely backfills a missed Paddle notification by exact verified email/customer and the configured catalog. Browser checkout success is never trusted for access.

Signed-in account with a uniquely verified email required6 requests / 5 minutes; server cooldown also applies
RequestEmpty JSON object.
Success response{"ok":true,"viewer":{"premium":true},"reconciliation":{"attempted":true,"updated":true,"state":"updated"}}
Errors / notes401 login required. Remote/storage/catalog failures are reported as a fail-closed reconciliation state without exposing Paddle identifiers.
POST /api/billing/portal Create billing portal session

Creates a short-lived Paddle customer-portal URL for subscription management.

Account cookie with mapped Paddle customer requiredStandard
RequestEmpty JSON object.
Success response{"ok":true,"url":"https://…"}
Errors / notes401 login required · 404 no billing profile · 503 Paddle unavailable.

Sound packs

Discover, preview, upload, and download community sound packs.

Website integration
GET /api/packs Search packs

Returns up to 200 packs filtered by free-text query and style.

Website session; personal API keys are outside this scopeStandard
RequestQuery: q (optional), style (optional).
Success response{"count":1,"items":[{"id":"…","title":"Drum Kit","style":"Drums","downloads":12}]}
Errors / notesNo endpoint-specific errors.
POST /api/packs Upload a pack

Publishes an account-owned public sound or Premium multi-file/unlisted bundle, up to 1 GiB.

Account cookie requiredStandard
Requestmultipart/form-data: file (repeat), title (2-120), style, optional bpm/key/tags/description, visibility=public|unlisted, optional share_expires_at.
Success response{"ok":true,"pack_id":"…","file_count":1,"share_url":"/packs/share/…"}
Errors / notes400 invalid metadata/file · 401 login required · 403 ENTITLEMENT_REQUIRED · 409 storage full · 413 payload too large.
GET /api/packs/<pack_id>/preview Preview a pack

Streams the stored pack asset inline when a previewable file is available.

Website session; personal API keys are outside this scopeStandard
RequestPath parameter: pack_id.
Success responseBinary file response.
Errors / notes404 when the pack/file is unavailable.
GET /api/packs/<pack_id>/download Download a pack

Downloads a pack attachment and increments its download count.

Account cookie requiredStandard
RequestPath parameter: pack_id.
Success responseBinary attachment.
Errors / notes401 login required · 404 when unavailable.
POST /api/packs/<pack_id>/share Rotate unlisted share link

Moves an owned pack between public and unlisted state and replaces any previous share token.

Premium pack owner cookie requiredStandard
RequestJSON: {"enabled":true,"expires_at":1893456000}
Success response{"ok":true,"visibility":"unlisted","share_url":"/packs/share/…"}
Errors / notes401 login required · 403 ENTITLEMENT_REQUIRED · 404 pack not found.
GET /api/packs/analytics Read pack analytics

Returns 7-90 days of aggregate preview and download counts for the account's packs.

Premium creator cookie requiredStandard
RequestQuery: days=7..90 (default 90).
Success response{"ok":true,"days":90,"items":[{"day":"2026-08-09","previews":4,"downloads":1}]}
Errors / notes401 login required · 403 ENTITLEMENT_REQUIRED.
GET /api/packs/share/<token>/preview Preview unlisted pack

Streams the first audio file while the revocable share token remains valid.

Valid unlisted share tokenStandard
RequestPath parameter: opaque token from the owner.
Success responseBinary inline audio response.
Errors / notes404 invalid, expired, or replaced token.
GET /api/packs/share/<token>/download Download unlisted pack

Downloads the shared audio or a ZIP for a multi-file bundle.

Valid unlisted share tokenStandard
RequestPath parameter: opaque token from the owner.
Success responseBinary audio or ZIP attachment.
Errors / notes404 invalid, expired, or replaced token.

Community

Read community content and perform signed-in social actions.

Website integration
GET /api/community/posts List posts

Returns up to 200 community posts with optional search, category, and sorting.

Website session; personal API keys are outside this scopeStandard
RequestQuery: q, cat, and sort=hot|new (all optional).
Success response{"items":[{"id":"…","title":"Mix feedback","category":"Feedback","upvotes":4}]}
Errors / notesNo endpoint-specific errors.
POST /api/community/posts Create a post

Publishes a post as the signed-in account.

Account cookie requiredStandard
RequestJSON: {"title":"3-160 chars","content":"up to 12000 chars","category":"Feedback"}.
Success response{"ok": true}
Errors / notes400 invalid title/content · 401 login required. Unknown categories fall back to General.
GET /api/community/posts/<pid> Read post and comments

Returns one post, its comments, vote totals, and user_voted state for the current account.

Website session; personal API keys are outside this scopeStandard
RequestPath parameter: pid.
Success response{"post":{"id":"…","user_voted":false},"comments":[]}
Errors / notes404 when the post does not exist.
POST /api/community/posts/<pid>/upvote Toggle post vote

Adds or removes the current account's upvote.

Account cookie requiredStandard
RequestPath parameter: pid. No request body.
Success response{"voted":true,"upvotes":5}
Errors / notes401 login required · 404 post not found.
POST /api/community/posts/<pid>/comments Add a comment

Adds a non-empty comment of up to 6,000 characters.

Account cookie requiredStandard
RequestJSON: {"content":"Your feedback"}
Success response{"ok": true}
Errors / notes400 invalid content · 401 login required · 404 post not found.
POST /api/community/comments/<cid>/upvote Toggle comment vote

Adds or removes the current account's comment upvote.

Account cookie requiredStandard
RequestPath parameter: cid. No request body.
Success response{"ok": true}
Errors / notes401 login required · 404 comment not found.
GET /api/community/drafts List drafts and scheduled posts

Returns up to 50 account-owned drafts and scheduled posts for the planning workspace.

Premium account cookie requiredStandard
RequestNo request body.
Success response{"ok":true,"items":[{"id":"…","state":"draft","title":"…"}]}
Errors / notes401 login required · 403 ENTITLEMENT_REQUIRED.
PATCH /api/community/posts/<pid>/draft Update or publish draft

Updates an owned draft/scheduled post and can publish it immediately or choose a validated future time.

Premium draft owner cookie requiredStandard
RequestJSON: {"title":"…","content":"…","category":"Feedback","state":"draft|scheduled|published","scheduled_at":1893456000}
Success response{"ok":true,"id":"…","state":"published"}
Errors / notes400 invalid fields/time · 403 ENTITLEMENT_REQUIRED · 404 draft not found · 409 already published.
DELETE /api/community/posts/<pid>/draft Delete draft

Deletes an owned draft or scheduled post before publication.

Premium draft owner cookie requiredStandard
RequestPath parameter: pid.
Success response{"ok":true}
Errors / notes403 ENTITLEMENT_REQUIRED · 404 draft not found · 409 already published.
GET /api/community/follows List saved threads

Returns the account's saved public threads for later review.

Premium account cookie requiredStandard
RequestNo request body.
Success response{"ok":true,"items":[{"id":"…","title":"…","comment_count":3}]}
Errors / notes401 login required · 403 ENTITLEMENT_REQUIRED.
POST /api/community/posts/<pid>/follow Save or follow thread

Stores bookmark and weekly-review preferences for one thread without instant push notifications.

Premium account cookie requiredStandard
RequestJSON: {"bookmarked":true,"weekly_digest":false}
Success response{"ok":true,"bookmarked":true,"weekly_digest":false}
Errors / notes401 login required · 403 ENTITLEMENT_REQUIRED · 404 post not found.
PATCH /api/community/posts/<pid>/feedback Resolve structured feedback

Marks an owned structured feedback request open/resolved and optionally identifies one helpful comment.

Premium post owner cookie requiredStandard
RequestJSON: {"status":"resolved","accepted_comment_id":"…"}
Success response{"ok":true,"status":"resolved","accepted_comment_id":"…"}
Errors / notes400 invalid status · 403 ENTITLEMENT_REQUIRED · 404 post/comment not found.

Artist pages

Build and publish the signed-in account's Artist Page at /artistpage. These website-only operations reject personal API keys and require the owning account session. Mutations require a trusted Origin and the X-CSRF-Token returned by the configuration. Uploaded artist images persist separately from temporary mastering audio.

Website integration
GET /api/linktree/config Read artist-page config

Returns the saved configuration or an editable default, owner media library, limits, publication revision and session-bound CSRF token. /api/artistpage/config is the canonical equivalent; the old path remains compatible.

Account cookie requiredStandard
RequestNo request body.
Success response{"ok":true,"alias":"artist","profile_name":"Artist","bio":"…","avatar_url":"","links":[],"theme":"dark"}
Errors / notes401 login required.
POST /api/linktree/config Publish artist-page config

Publishes a verified account's profile, owned artwork, layout and validated HTTP(S) links. Use limits.max_links (up to 25 with full access). /api/artistpage/config is equivalent. Include base_revision from GET to detect edits made in another tab.

Verified owner cookie + trusted Origin + X-CSRF-Token30 publications/minute/account
RequestJSON: {"alias":"artist","profile_name":"Artist","bio":"…","avatar_url":"","links":[{"label":"Listen","url":"https://…"}],"theme":"dark","design":{"layout":"studio"},"base_revision":null}. X-CSRF-Token is required.
Success response{"ok":true,"published":true,"public_url":"https://orynosmusic.com/artistpage/artist","revision":"64 hex digits","assets":[]}
Errors / notes400 invalid fields/URLs · 401 login required · 403 origin/CSRF/verification · 409 alias taken or ARTIST_CONFLICT · 429 rate limited.
GET /api/artistpage/alias Check an artist-page address

Checks syntax and case-insensitive conflicts without publishing a page.

Account cookie required90 checks/minute/account
RequestQuery: alias (3–48 lowercase letters, digits, underscores or hyphens).
Success response{"ok":true,"alias":"artist","valid":true,"available":true}
Errors / notes401 login required · 429 rate limited.
POST /api/artistpage/media Upload artist artwork

Validates and re-encodes one still JPEG, PNG or WebP, stripping metadata. Original limit 8 MiB/24 megapixels; stored images at most 2 MiB. Library limit 64 images/24 MiB per account. Unpublished images are owner-only; referenced published artwork is public.

Verified owner cookie + trusted Origin + X-CSRF-Token10 uploads/minute/account; three decoder slots
RequestMultipart: file and kind (avatar/cover/background/icon/artwork). Optional crop JSON is validated. SVG/HTML and animated images are rejected.
Success response{"ok":true,"asset":{"id":"…","url":"/artistpage/media/….webp","width":1024,"height":1024},"assets":[]}
Errors / notes400 invalid image/crop · 401 login required · 403 ownership/verification/origin/CSRF · 413 image/library limit · 429 busy/rate limit · 503 decoder/storage unavailable.
DELETE /api/artistpage/media/<asset_id> Remove unused artist artwork

Removes only an unused image belonging to the signed-in account. Replace or remove a published reference and publish first. The editor asks before permanent removal.

Verified owner cookie + trusted Origin + X-CSRF-Token30 removals/minute/account
RequestOwned asset ID in URL; no body.
Success response{"ok":true,"assets":[]}
Errors / notes401 login required · 403 verification/origin/CSRF · 404 not owned/found · 409 ARTIST_MEDIA_IN_USE · 429 rate limit.
POST /api/artistpage/preview Preview an artist page

Returns the real public template with inert links and no scripts. Does not publish changes, create media or count views. Email verification is required later for uploads and publication.

Owner cookie + trusted Origin + X-CSRF-Token150 previews/minute/account
RequestJSON profile/configuration using the same validated design and link fields as publication.
Success response{"ok":true,"html":"<!doctype html>…"}
Errors / notes400 invalid fields · 401 login required · 403 origin/CSRF/ownership · 429 rate limit.
GET /api/linktree/analytics Read artist-page analytics

Returns privacy-safe aggregate page views and stable per-link click counts: seven days normally, or 90 days with link.analytics_90d (included for eligible verified accounts during the temporary Free phase).

Page owner cookie requiredStandard
RequestNo request body.
Success response{"ok":true,"days":90,"items":[{"day":"2026-08-09","link_id":"page","page_views":5,"clicks":0}]}
Errors / notes401 login required.

DSP profiles & Discord

Adaptive DSP paths, private reference profiles, account connections and measured comparisons.

Website integration
GET /api/studio/catalog Read studio catalog

Lists current model/module eligibility, private reference-profile metadata and catalog information. Use /api/credits for model credit prices and wallet balance.

Personal account API key or website sessionStandard
RequestNo body.
Success response{"engines":[],"models":[],"discord":null,"discord_available":false,"premium":false}
Errors / notes401 missing website/API access.
POST /api/studio/models Learn a custom DSP profile

Learns robust spectral and dynamics statistics from 3–8 different mastered references. Saves statistics, not uploaded audio. Up to five private profiles.

Personal account API key or eligible website accountStandard; one active training slot
RequestMultipart: name and references (3–8 WAV/FLAC/AIFF, 32 MB each, 100 MB total). Analyses up to 60 seconds per file.
Success response{"success":true,"id":"…","name":"My sound","profile":{}}
Errors / notes400 invalid/duplicate references or quota · 401 sign in · 403 Pro required · 413 too large · 503 busy.
DELETE /api/studio/models/<model_id> Delete your DSP profile

Deletes a saved profile belonging to the current account.

Personal account API key or owning website accountStandard
RequestProfile ID in URL.
Success response{"success":true}
Errors / notes401 sign in · 404 profile not owned/found.
POST /api/account/discord/start Start Discord connection

Starts the identify-only authorization-code flow. A single-use state is bound to the logged-in account and expires after ten minutes.

Account cookie requiredStandard
RequestNo body.
Success response{"url":"https://discord.com/oauth2/authorize?…"}
Errors / notes401 sign in · 503 Discord OAuth not configured.
DELETE /api/account/discord Disconnect Discord

Removes the verified identity link and disables member-only DSP recipes and listening packs.

Account cookie requiredStandard
RequestNo body.
Success response{"success":true}
Errors / notes401 sign in.
POST /api/studio/feedback Save render feedback

Appends satisfaction and an optional comment to the private UTF-8 feedback text file. Render receipts expire after 30 days.

Personal key for the render-owning account or owning website sessionStandard; once per render
RequestJSON: {"render_id":"…","satisfied":true,"comment":"…"} (comment ≤2,000 characters).
Success response{"success":true}
Errors / notes400 invalid satisfaction/comment · 401 sign in · 404 render not owned/found · 409 already submitted.

AI models & credits

Account-bound weekly and permanent mastering credits.

Website integration
GET /api/credits Read credit balance and AI models

Returns model prices, weekly/purchased credit balances, reset time and current eligibility. During the temporary Free phase ordinary verified accounts receive 5,000 weekly credits and full model/module access; normal rendering still spends credits. Paid-mode Free/Pro allowances remain policy-dependent.

Personal account API key or verified website accountStandard
RequestNo body.
Success response{"wallet":{"weekly":5000,"purchased":0,"total":5000},"models":[],"free_access_policy":{"active":true,"weekly_credits":5000}}
Errors / notes401 sign in required.
POST /api/credits/checkout Start a credit-pack checkout

Creates an account-bound one-time Paddle intent. Credits are granted only by verified transaction.completed, never by a browser callback.

Verified Pro account cookieStandard
RequestJSON: {"pack":"1000"}; alternatives 2500 or 10000.
Success response{"price_id":"pri_…","credit_intent":"…","client_token":"…","environment":"sandbox","customer_email":"…"}
Errors / notes400 unknown pack · 401 sign in · 403 Pro/email required · 503 Paddle price/catalog unavailable.

Owner administration

First-party owner console; an Admin membership does not grant console access. Responses are private. Writes require a live owner cookie, trusted origin and X-Admin-CSRF from the /admin session.

Website integration
GET /api/admin/model-usage Read weekly model usage

Returns actual completed generations, tracks, distinct accounts and charged credits by model and analysis mode for the requested UTC credit week. Completed totals exclude pending and refunded work; reserved, refunded and other states are reported separately.

Configured owner cookie only; personal API keys excludedStandard
RequestOne optional non-negative integer week index returned by week.index; omit for the current UTC credit week. No body.
Success response{"week":{"index":0,"start":0,"end":604800},"models":[],"totals":{}}
Errors / notes400 invalid week or extra query fields; 401 or 403 owner authorization required.
GET /api/admin/downloads Read desktop download and update metrics

Returns aggregate desktop installer download starts, update download starts, update checks and authenticated client version changes. These counters do not prove completed installs. A first client observation establishes a version baseline; VST3 1.3 does not report installed versions.

Configured owner cookie only; personal API keys excludedStandard
RequestNo body.
Success response{"started_at":0,"totals":[],"versions":[],"daily":[],"update_reporting":{"studio":"Authenticated client reports; first observation establishes a baseline.","vst3":"VST3 1.3 does not report installed versions. Zero reports does not mean no updates."}}
Errors / notes403 configured owner required.
GET /api/admin/users Search accounts

Searches usernames and emails; returns up to 500 matches with rank, purchased balance, weekly usage and ban status.

Configured owner cookie onlyStandard
RequestQuery: q (up to 100 characters).
Success response{"users":[{"id":"…","username":"…","purchased":0,"weekly_used":0,"ban_reason":null}]}
Errors / notes403 owner required.
POST /api/admin/users/<uid> Change membership, credits or ban

Audited account updates. Ban revokes existing sessions; requires a reason. Configured owner cannot be banned or lose Admin membership. Paid subscriptions remain billing-managed.

Owner cookie + X-Admin-CSRFStandard
RequestJSON: {"action":"change","rank":"dayone","purchased":1000}; rank may be empty, influencer, admin, dayone, or orynos. Or {"action":"ban","reason":"…"} / {"action":"unban"}.
Success response{"ok":true}
Errors / notes400 invalid values · 403 owner/origin/nonce required · 404 account absent · 409 owner protection.
GET /api/admin/content Search moderation content

Lists up to 200 packs or comments including recoverable removals.

Configured owner cookie onlyStandard
RequestQuery: kind=pack|comment, q (up to 100 characters).
Success response{"items":[{"id":"…","title":"…","hidden_reason":null}]}
Errors / notes400 kind invalid · 403 owner required.
POST /api/admin/content/<kind>/<oid> Remove or restore community content

Audited, reversible removal. Removed packs cannot be previewed/downloaded through public, owner or shared URLs. Published pack files stay stored.

Owner cookie + X-Admin-CSRFStandard
Requestkind=pack|comment. JSON: {"action":"delete","reason":"…"} or {"action":"restore"}.
Success response{"ok":true,"restorable":true}
Errors / notes400 invalid action/reason · 403 owner/origin/nonce required · 404 content absent.

DAW plugin account protocol

Native public-client PKCE connection, with signed 24-hour offline licences, rotated 30-day refresh sessions and at most three installations. Native endpoints reject Origin headers and cookies; no website API key is needed. Browser consent and device management use verified first-party accounts and trusted origins. Audio never enters this protocol.

Website integration
POST /api/plugin/auth/client-version Report an authenticated native client version

Records an installed product version against the verified active native device account. First observation establishes a baseline; a higher version increments the aggregate client-update counter. Repeated versions and downgrades are ignored without changing the baseline.

Native device-bound refresh credential; no cookies or Origin; personal API keys do not authorize this protocol90 native requests/minute/IP
RequestJSON: {"device":"64 hex digits","refresh":"64-character native refresh credential","app":"studio","version":"0.9.15"}. app is studio or vst3; version is major.minor.patch with components ≤65535. Body ≤4 KiB; no URL query.
Success response{"status":"recorded","reason":"updated","version":"0.9.15"} or {"status":"ignored","reason":"first_seen|same_version|downgrade","version":"0.9.15"}
Errors / notes400 invalid fields/version/query · 401 REAUTH_REQUIRED · 403 NATIVE_ONLY for browser requests · 413 body limit · 415 JSON required · 429 RATE_LIMIT.
GET /api/plugin/license-key Read licence verification key

Returns the P-256 public key. The release binary pins it; it does not trust arbitrary runtime keys. No private signing key is exposed.

Native client; no cookies or Origin90 native requests/minute/IP
RequestNo body.
Success response{"algorithm":"ES256","kid":"…","x":"64 hex digits","y":"64 hex digits","issuer":"orynosmusic.com","audience":"orynos-vst3"}
Errors / notes403 browser request · 429 rate limited.
POST /api/plugin/auth/start Start native sign-in

Creates a ten-minute PKCE request. User must open the website and approve the matching six-digit code after signing in and verifying email.

Native client; no cookies or Origin90 native requests/minute/IP
RequestJSON: {"device":"random 64-hex installation ID","challenge":"43-character base64url SHA-256 of PKCE verifier"}. Body ≤4 KiB.
Success response{"request":"…","poll":"…","code":"123456","authorize_url":"https://orynosmusic.com/plugin/authorize?request=…","expires":"600","interval":"2"}
Errors / notes400 invalid fields · 403 browser · 413 body limit · 429 rate limit · 503 busy/configuration.
POST /api/plugin/authorize Approve or decline your DAW

Browser consent only. Matches a pending request and code. Denied or used requests cannot be reused.

Verified account cookie + trusted origin90 requests/minute/IP
RequestJSON: {"request":"43-character request ID","code":"six digits","approve":true}. Use false to decline.
Success response{"status":"approved"}
Errors / notes400 expired/code mismatch · 401 sign in · 403 verification/origin required · 429 attempts.
POST /api/plugin/auth/poll Complete native PKCE sign-in

Consumes an approved grant once. Returns a signed device-bound entitlement and opaque refresh credential. Membership is checked server-side.

Native request secret + PKCE verifier90 native requests/minute/IP; poll every two seconds
RequestJSON: {"request":"…","poll":"…","verifier":"43–128 base64url characters"}. Keep credentials private.
Success response{"status":"ready","license":"signed token","refresh":"rotating credential","expires":"Unix seconds","user":"…","tier":"free"}
Errors / notes202 pending · 400 invalid fields · 401 invalid/expired/used grant · 403 denied or unverified · 409 device limit · 429 attempts.
POST /api/plugin/auth/refresh Refresh native entitlement

Rotates the refresh credential once under a transaction, checks live email verification, ban, auth version and membership, and signs a new 24-hour lease.

Native device-bound refresh credential90 native requests/minute/IP
RequestJSON: {"device":"64 hex digits","refresh":"64-character credential"}. Persist the newly returned refresh value encrypted.
Success response{"status":"ready","license":"signed token","refresh":"new credential","expires":"Unix seconds","user":"…","tier":"pro"}
Errors / notes400 invalid fields · 401 REAUTH_REQUIRED · 403 browser · 429 attempts.
POST /api/plugin/auth/disconnect Disconnect native installation

Deletes the matching server device session. Already-issued offline leases expire within 24 hours.

Native refresh credential90 native requests/minute/IP
RequestJSON: {"device":"64 hex digits","refresh":"64-character credential"}.
Success response{"status":"disconnected"}
Errors / notes400 invalid fields · 403 browser · 429 attempts.
GET /api/plugin/devices List your DAW installations

Returns only the current account’s device records, with masked installation IDs and connection timestamps.

Live account cookieStandard
RequestNo body.
Success response{"devices":[{"id":"32 hex digits","device":"last 8 digits","created_at":0,"last_seen":0}]}
Errors / notes401 sign in.
POST /api/plugin/devices/revoke Revoke a DAW installation

Deletes only the caller-owned device session. Offline leases last no more than 24 hours.

Live account cookie + trusted originStandard
RequestJSON: {"id":"32-hex device record ID"}.
Success response{"status":"revoked"}
Errors / notes400 invalid ID · 401 sign in · 403 origin.

Native DAW export

Explicit Export + Master handoff from Orynos Studio. Local editing and ordinary WAV export work offline. Verified Free/Pro accounts use the existing website model eligibility, render modes, credits, RAM admission and queue; completed output lasts five minutes. Native endpoints reject cookies, Origin headers and URL queries.

Website integration
GET /api/daw/update Read the official signed desktop update

Returns a purpose-separated ODU1 P-256 signature anchored in the existing native pinned key, after checking the published package's actual SHA-256, size, version and official path. This integrity signature is separate from Windows Authenticode; the preview installer remains unsigned. Client rejects downgrades and asks for licence review if terms change.

Native client; no cookies or Origin90 native requests/minute/client
RequestNo body, account token or URL query. The native updater checks asynchronously on actual app startup.
Success response{"status":"ready","manifest":"base64url(ODU1|issuer|audience|platform|version|size|sha256|path|issued|expires|terms_id).base64url(raw P256 signature)"}
Errors / notes403 browser request · 429 rate limit · 503 UPDATE_UNAVAILABLE if published metadata/package cannot be verified. Signed manifests expire after fifteen minutes; package limit 128 MiB.
POST /api/daw/session Create a scoped DAW export session

Checks the live verified account/device and creates a six-hour opaque DAW token, stored only as a hash. Does not rotate the shared account refresh credential. Revocation/authentication changes invalidate the scoped token.

Native device-bound refresh credential90 native requests/minute/client
RequestJSON: {"device":"64 hex digits","refresh":"64-character account refresh credential"}. Body ≤4 KiB. Never include this credential in audio uploads.
Success response{"status":"ready","session":"64-character opaque DAW token","expires":"Unix seconds"}
Errors / notes400 invalid fields/query · 401 REAUTH_REQUIRED · 403 browser request · 411 missing length · 413 body limit · 415 format · 429 rate limit.
POST /api/daw/master Submit a confirmed DAW WAV export

Adapts one explicitly confirmed export to /api/master. Reusing an accepted device/request ID returns its original job without a second reservation. Model eligibility, temporary Free access and normal render credit charges follow the verified account’s current catalog policy. Native delivery is one WAV; use the website studio for packages/reference/layer workflows.

Authorization: Bearer scoped DAW token90 native requests/minute/client; existing per-device render concurrency/RAM/queue limits
RequestMultipart: file (one WAV, ≤250 MiB), model (premier/galaxy/sun/whitehole/aurora/blackhole), mode (normal/power/ultra/max), settings (JSON object ≤64 KiB), request_id (fresh 32 hex digits), consent="export-and-master-v1". Model/mode compatibility and costs use the authoritative render plan. Existing Studio builds can use the current models exposed by their model selector.
Success response{"status":"queued","job_id":"UUID"}
Errors / notes400 invalid export/consent/model/mode/audio · 401 revoked session · 402 INSUFFICIENT_CREDITS · 403 Pro/feature required · 409 duplicate pending/failed export · 413 upload limit · 429 concurrency/rate limit · 503 bounded queue capacity.
GET /api/daw/job/<job_id> Read private DAW render progress

Uses the shared job ownership check and returns flat progress fields for the native client. Queue and processing limits are separate from the five-minute completed-output window.

Owning account/device scoped DAW token90 native requests/minute/client; poll every two seconds
RequestJob UUID in the path; no body or URL query.
Success response{"status":"processing","job_id":"UUID","progress":"45","phase":"Applying master","error":"","output_filename":"","expires_at":"0","retention_seconds":"300"}
Errors / notes401 revoked/expired session · 403 browser · 404 job not owned/found · 410 RESULT_EXPIRED · 429 rate limit.
GET /api/daw/download/<job_id> Download a private completed DAW WAV

Downloads the owning device's completed WAV through the existing private download view. Finished audio expires five minutes after processing completes. The native client saves a new local file beside its original export.

Owning account/device scoped DAW token90 native requests/minute/client
RequestJob UUID in the path; no body or URL query.
Success responseaudio/wav attachment; no-store.
Errors / notes401 revoked/expired session · 403 browser · 404 not owned/found/expired · 409 WAV_REQUIRED · 429 rate limit.
POST /api/daw/cancel/<job_id> Cancel a queued DAW export or stop waiting

A queued job is removed safely and reserved credits are refunded once by the normal credit transaction. If a worker already took it, the server render continues and a successful master still spends credits; stopping native waiting does not promise a processing refund.

Owning account/device scoped DAW token90 native requests/minute/client
RequestJob UUID in the path. JSON: {} (≤4 KiB).
Success response{"status":"cancelled","refunded":"true"} or {"status":"render_continues","refunded":"false","message":"…"}
Errors / notes401 revoked/expired session · 403 browser · 404 job not owned/found · 411 missing length · 413 body limit · 415 format · 429 rate limit.

AI client connections

MCP over authenticated HTTP. Client-specific setup and compatibility are documented at /mcp.

Website integration
POST /api/mcp Call the OrynosMusic MCP server

JSON-RPC tools reuse the existing account, model eligibility, upload ownership, render queue and credit reservation. Mastering requires explicit confirm_credit_charge=true. No audio is transferred through the model context. This endpoint does not accept website sessions or installation-wide keys.

Authorization: Bearer personal account API key; verified active account requiredMCP account request limit plus the original tool endpoint limits
Requestapplication/json MCP request. Use tools/list to discover current tools and their schemas. Upload audio once through multipart POST /api/analyze using the same personal key; pass its upload_id to the appropriate MCP tool. Setup: /mcp.
Success responseMCP JSON-RPC response. Completed result links require the same owning account credential; the five-minute RAM download window starts after rendering completes.
Errors / notes400 malformed or incompatible request · 401 invalid/revoked key · 403 untrusted origin · 413 body too large · 415 unsupported content type · 429 account rate limit. Tool failures preserve ordinary API validation and credit rules.

Settings and models.

Start with the minimal examples. Add advanced processing only when you need direct control.

Master settings

A minimal payload for streaming-focused material.

  • presetAI, DSP_MudCleaner, Glue, Punchy, Smooth, or EDM.
  • target_lufsClamped from −18 to −8 LUFS.
  • ceilingClamped from −3 to −0.1 dBTP.
  • bitdepth16, 24, or 32; invalid values become 24.
  • bass_adj / mid_adj / high_adjManual tone, each −12 to +12 dB.
  • width / saturationWidth 0.5-1.5; saturation 0-6.

Spatial mastering

Enable a packaged spatial export only when the client can consume ZIP results.

  • binaural_spatial_masterCreates a headphone-ready binaural master.
  • adm_exportAdds ADM/BW64 assets and metadata where available.
  • spatial_amount0-1 intensity.
  • spatial_sample_rate48,000 or 96,000 Hz.

Mix settings

Routing follows the order of repeated multipart stem files. Categories normalize to drums, bass, vocals, music, and fx.

  • styleclean, punchy, warm, or aggressive, plus headroom, vocal presence, sequence intelligence, reverb, delay, ducking, and limiter controls.
  • routing[]index, category, gain trim (−18…18 dB), pan (−1…1), compression (0…1), width (0…2), filters, polarity, solo/mute, and sends.
  • busesPer-category gain, glue, tone (neutral/bright/dark), width, reverb, and delay sends.
  • render.output_srSource/null, 44.1, 48, 88.2, 96, 176.4, or 192 kHz.
  • render.bitdepth16 or 24-bit WAV output.
  • reference_matchSet true and include the reference multipart file.
minimal-master-settings.json
{
  "preset": "AI",
  "ai_model": "premier", "target_lufs": -14,
  "ceiling": -1,
  "bitdepth": 24
}

Errors, limits, and retries.

Check HTTP status and JSON error bodies before treating a response as audio. Back off when the server tells you to.

StatusCode / conditionWhat to do
400Invalid inputFix field names, multipart parts, JSON settings, formats, or bounds. Do not retry unchanged.
401API_KEY_REQUIRED / API_KEY_OR_LOGIN_REQUIREDSend an active personal key belonging to a verified account. Never place it in the URL.
402INSUFFICIENT_CREDITSCheck the owning account's balance and the selected model/mode cost. Temporary Free access still consumes normal rendering credits.
403Invalid session originFor website-cookie mutations, use the same origin. Header-key server calls are not cross-site browser calls.
404Missing or non-owned job/resourceConfirm the ID and owning account. Completed job results may already have expired.
413PAYLOAD_TOO_LARGE / file limitReduce upload size or split the workload within the documented endpoint limits.
429RATE_LIMITED / CONCURRENCY_LIMITHonor Retry-After when present; otherwise wait for an active mastering job to finish.
503QUEUE_FULL / MIX_BUSYRetry with exponential backoff and jitter. Avoid synchronized retry storms.
500Processing errorLog a request correlation on your side, retry once if safe, then contact support without sending API keys.

Upload limits

Analyze/master audio: 250 MiB. Master: up to 24 tracks. Mix: 96 WAV stems / 900 MiB total. Mix stem duration: 12 minutes each.

Job lifetime

Queued jobs have a 30-minute waiting limit. Processing uses a separate mode-dependent limit, up to two hours. The 5-minute finished-audio lifetime starts at completion. Audio is stored in memory; a process restart removes it.

Rate-limit headers

A global 429 response includes Retry-After in seconds. Apply exponential backoff plus a small random delay.

Transport

Use HTTPS in production, long upload/render timeouts, streaming downloads, and automatic multipart boundaries generated by your HTTP client.

API support

Bring the request, response status, and a redacted error to Discord. Never post an API key, reset token, or private audio URL.

Open Discord
Confirm your email address to receive subscription and account notices.