Sound Effects API
Not generally available. The Sound Effects API is in private beta and is not yet enabled in production. Access is by request only, per user. No model is switched on until Demeterics enables it, so calls return an error today.
To request access, email sales@demeterics.com with:
- Subject: "Feature Access Request"
- Feature name: "Sound Effects (SFX)"
The Demeterics Sound Effects API turns a text prompt into a short audio clip (a door slam, rain on a tin roof, a looping engine hum) through one endpoint, while tracking usage and cost and storing the generated audio.
Overview
Base URL: https://api.demeterics.com/sfx/v1
Providers: elevenlabs (default) and stability.
Features:
- One request shape for both providers
- Per-user cache: an identical request is served again for $0
- Re-roll controls:
cache: false,variantandseed - Idempotency: safe retries with an
Idempotency-Keyheader - BYOK: use your own provider key
- Audio storage: generated audio is stored in GCS and returned by 15-minute signed URL on request
Access
Access has two gates, and both must be open:
- User opt-in. Your account needs the
FeatureSFXgrant. It is off by default and is given per user. Without it you get HTTP 403feature_access_required. - Model enabled. Demeterics enables each model individually. A model that is not enabled returns HTTP 400
model_not_enabled. UseGET /sfx/v1/modelsto see what is enabled for the service right now (an empty list means nothing is live).
Zero Data Retention (ZDR) accounts cannot use this endpoint, because the prompt is sent to the vendor.
Authentication
Managed Keys (Default)
curl -X POST https://api.demeterics.com/sfx/v1/generate \
-H "Authorization: Bearer dmt_your_api_key" \
-H "Content-Type: application/json" \
-d '{"provider":"elevenlabs","prompt":"heavy wooden door slam in a stone hallway","duration_seconds":2}' \
--output door.mp3
Bring Your Own Key (BYOK)
Send both keys, separated by a semicolon:
curl -X POST https://api.demeterics.com/sfx/v1/generate \
-H "Authorization: Bearer dmt_your_api_key;your_provider_key" \
-H "Content-Type: application/json" \
-d '{...}'
The format is [demeterics_api_key];[provider_api_key]. Provider costs are then billed by the provider to your own account, and the BYOK service fee applies instead of the managed one.
Endpoints
Generate a sound effect
POST /sfx/v1/generate (also available at /api/sfx/v1/generate)
Request body (unknown fields are rejected with 400):
| Field | Type | Required | Description |
|---|---|---|---|
prompt |
string | Yes | What the sound is. /// APP, /// FLOW, /// ENV, /// USER tag lines are removed before the vendor sees the prompt. |
duration_seconds |
number | Yes | elevenlabs: 0.5 to 22. stability: whole seconds, 1 to 190. |
provider |
string | No | elevenlabs (default) or stability |
model |
string | No | elevenlabs: eleven_text_to_sound_v3 (default), eleven_text_to_sound_v2 (deprecated by the vendor, removal 2027-03-01). stability: stable-audio-2. Stability picks the model by endpoint, so never send anything else. |
output_format |
string | No | mp3 (default) or wav. ElevenLabs returns wav only for non-looping effects. |
loop |
boolean | No | elevenlabs only. Ask for a seamless loop (use with mp3). |
prompt_influence |
number | No | elevenlabs only, 0 to 1. Higher follows the prompt more literally. |
steps |
integer | No | stability only. Diffusion steps. |
seed |
integer | No | Part of the cache key. It is not sent to the vendor. |
variant |
integer | No | Re-roll number. A new value is a new take. See Cache. |
cache |
boolean | No | Default true. false skips the cache. |
A parameter that belongs to the other provider is a 400 validation_error.
Response (default): raw audio bytes (audio/mpeg or audio/wav).
| Header | Meaning |
|---|---|
X-Cost-USD |
What this request cost you, in USD. 0.000000 on a cache hit. |
X-Duration-Seconds |
Duration of the clip |
X-Cache |
HIT, MISS or BYPASS (see Cache) |
X-Transaction-ID |
Transaction ID (sfx_...) |
Response with ?response_format=json:
{
"id": "sfx_01...",
"provider": "elevenlabs",
"model": "eleven_text_to_sound_v3",
"duration_seconds": 2,
"cost_usd": 0.0,
"cache": "MISS",
"audio_url": "https://storage.googleapis.com/...",
"usage": { "unit": "seconds", "billed_units": 2 },
"metadata": { "format": "mp3", "generation_ms": 3100 }
}
audio_url is a signed URL valid for 15 minutes. Only if no URL could be signed does the response carry audio_base64 instead. (cost_usd above is a placeholder, not a price.)
List models
GET /sfx/v1/models returns the models that are enabled right now, each with pricing_unit, price_per_unit_usd, and its duration limits. Rates are always per unit, never per request.
Cache (per user)
By default (cache: true) the result of a request is stored for 30 days under a key built from your user ID, your key type (managed or BYOK) and every parameter that changes the audio: provider, model, cleaned prompt, duration, loop, prompt_influence, steps, output_format, seed and variant. Nobody else can read or hit your entries.
X-Cache |
Meaning |
|---|---|
MISS |
Generated now and billed. |
HIT |
Replayed from your cache. No vendor call, $0. A $0 row is still logged for the request. |
BYPASS |
Neither cache nor idempotency was used (cache: false without an Idempotency-Key). Generated and billed. |
Getting a different take. Asking again with the same body returns the same audio. To re-roll, change variant (for example 1, 2, 3) or seed, or send cache: false. A QC retake loop should bump variant on each retry, so a bad take is never served again.
Idempotency-Key
Send Idempotency-Key: <1 to 255 printable ASCII characters> together with cache: false to make a retry safe without caching the content. With the default cache: true the content cache already gives the same protection and the header is ignored.
- The first request with a key generates and bills once. A retry with the same key and the same body replays the stored audio (
X-Cache: HIT, $0). The replay window is 24 hours. - A request that fails before it is billed releases the key, so you can retry it. A request that succeeded and was billed keeps the key, so a lost response replays instead of billing twice.
- A request that fails after the provider may already have charged for the work (an upstream timeout after the request was sent, a provider 5xx, or a reply with no usable audio) is billed as a failure and also releases the key and the cache entry. A retry is then a new generation and is billed again.
- If your client disconnects while a cached or keyed request is running, the generation still completes, is billed once and is stored. The retry gets 409 while it runs, then a $0 replay.
- If the stored audio of a cache entry or key is no longer available, the retry generates and bills again instead of failing.
- Keys are scoped to your user and to managed versus BYOK.
Errors
Errors are JSON: {"error": {"message": "...", "type": "<code>", "code": "<code>"}}.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request |
Malformed JSON or an unknown field |
| 400 | validation_error |
A field is missing, out of range, or for the other provider |
| 400 | model_not_enabled |
The model is not enabled by Demeterics |
| 400 | invalid_idempotency_key |
Key is empty, over 255 characters or not printable ASCII |
| 400 | no_provider_key |
No managed key for this provider; send a BYOK key |
| 400 | upstream_rejected |
The vendor refused the request before generating. Not charged. |
| 401 | authentication_required |
Missing or invalid API key |
| 402 | insufficient_credits |
Balance is below the estimated cost |
| 403 | feature_access_required |
Your account does not have FeatureSFX |
| 409 | request_in_progress |
Another request with the same cache entry or key is still running. Retry after the Retry-After delay (5 s). |
| 422 | idempotency_key_reused |
The key was already used with a different body |
| 429 | too_many_in_flight |
More than 4 effects generating at once for your user. Retry-After is set. |
| 429 | upstream_rate_limited |
The vendor rate limit. The vendor's Retry-After is passed through. |
| 502 | upstream_error |
The vendor failed, or rejected the provider key (HTTP 401/403). On the managed key the message is generic and quotes a transaction id for support; with BYOK it carries the vendor's reply. |
| 503 | pricing_unavailable, pricing_misconfigured, cache_unavailable, cache_read_failed |
A server-side problem; the request was not processed |
Retries. Honor Retry-After on every 409 and 429. Demeterics never retries a vendor call for you, and neither should a tight loop. If the vendor may have generated the audio and the response was then lost or unusable (an upstream timeout after the request was sent, a provider 5xx, or a broken audio read), the call is billed, the error type carries a _billed suffix in the usage log, and the cache entry or key is released, so a retry is billed again.
Pricing
Each model has a pricing unit, and the rate is shown per that unit, not per token and not per request:
| Provider | Unit | What is billed |
|---|---|---|
elevenlabs |
seconds |
The requested duration_seconds, rounded up to a whole second, times the per-second rate |
stability |
clip |
One generation, times the per-clip rate |
For current rates see Available Models, or GET /sfx/v1/models. Rates are set conservatively, and the vendor reports no usage or cost for these calls, so the charge is the rate times the units above. A service fee is added (managed or BYOK, as for other APIs). Cache hits and idempotent replays are $0. See Credits & Pricing.
Prompt guidance
- Describe what you would hear, not the frequency band. In live testing, an ElevenLabs prompt that said "sub-bass" together with "sparse midrange" produced energy almost entirely below 100 Hz, which is inaudible on most speakers and headphones. Say "deep low rumble with a soft thud", or name the object and the room, and keep some midrange in the description.
- Name the source, the material, the space and the action: "metal gate slides open on a rusty rail, echoing in a parking garage".
- Match the duration to the event. A single hit needs 1 to 3 seconds. For a bed or ambience use
loop: truewithmp3on ElevenLabs. - Use
prompt_influence(ElevenLabs) to trade literal prompt-following against variety. - To compare takes cheaply, re-roll with
variantinstead of rewriting the prompt.
Example: retake loop
for v in 1 2 3; do
curl -s -X POST "https://api.demeterics.com/sfx/v1/generate" \
-H "Authorization: Bearer $DEMETERICS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"prompt\":\"glass bottle rolling on a wooden floor\",\"duration_seconds\":4,\"variant\":$v}" \
-D headers_$v.txt --output take_$v.mp3
done