SFX v3 API Guide: Authentication, Requests & Audio Output

Compare the direct ElevenLabs sound-effects API with this platform’s task API. Learn authentication, model selection, quotes, polling and audio downloads.

Last updated: 2026-11-09

Choose the API you intend to use

There are two different request paths. ElevenLabs provides the official SFX v3 endpoint. This website has its own catalog, user keys, credits and asynchronous generation tasks. Their keys, model identifiers, request fields and response formats are not interchangeable.

When integrating through this website, choose a model suited to your task from the current platform audio catalog and use its returned identifier and parameters. The platform examples below document this website’s request contract. Direct ElevenLabs integration uses a separate account.

Path A: call ElevenLabs directly

Use an ElevenLabs key from your server environment as ELEVENLABS_API_KEY. This request uses the official model ID and writes a successful audio response to a file:

curl --fail --silent --show-error \
  --request POST \
  'https://api.elevenlabs.io/v1/sound-generation?output_format=mp3_44100_128' \
  --header "xi-api-key: ${ELEVENLABS_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "A small wooden drawer closes once with a soft tap.",
    "model_id": "eleven_text_to_sound_v3",
    "duration_seconds": 4,
    "prompt_influence": 0.3
  }' \
  --output sfx-v3.mp3

Check the command’s exit status before using the file. Do not treat an unsuccessful response as playable audio.

The official endpoint reference defines text, model_id, duration_seconds, prompt_influence and the output_format query parameter. Its specified-duration range is 0.5–30 seconds; prompt influence ranges from 0 to 1. Format access can depend on the ElevenLabs plan. These limits describe the direct API, not a promise about controls available on this site.

Current model documentation lists SFX v3 looping through loop: true. Check the current contract and audition the join before relying on it. Those provider details were checked on November 9, 2026.

Path B: inspect this platform’s catalog

Set SFX_BASE_URL to your deployment origin, for example https://your-site.example. The public catalog is a read-only starting point:

curl --fail --silent --show-error \
  "${SFX_BASE_URL}/api/ai/router01/models?type=audio"

Read the JSON code first. On success, data contains model entries with slug, name, type and params, alongside catalog pricing information. Use the returned slug and declared fields. An ElevenLabs model ID is not necessarily a platform slug.

You can also select a model, enter a prompt and review settings and credit estimates in the audio workspace. Music, speech and sound-effects models serve different purposes, so choose one suited to your task.

Authenticate platform generation and task requests

Sign in and create a user key in Settings → API Keys. Store it in the server environment as SFX_API_KEY. Use Authorization: Bearer … for generation and task polling. An ElevenLabs key cannot authenticate these platform requests.

Keep both services’ keys out of browser code and public repositories. User API keys are different from administrative credentials. If an explicit key is invalid, the platform does not fall back to a browser session.

Prepare one supported request and get a quote

Choose a model suited to your task from the catalog, replace the placeholder below with its slug and save the JSON as request.json:

{
  "mediaType": "music",
  "model": "REPLACE_WITH_AVAILABLE_SFX_SLUG",
  "prompt": "A small wooden drawer closes once with a soft tap.",
  "options": {
    "params": {}
  }
}

The platform’s current generation contract uses mediaType: "music" for audio requests, including compatible effects models. The public catalog uses the type audio. Sending mediaType: "audio" to the generation endpoint is not supported by its current parser.

Use the top-level prompt. Model-specific options belong in options.params and must match the selected model’s declared names, types and allowed values. Do not copy direct-API fields into this object by assumption. In particular, the platform does not use a top-level duration_seconds, and options.duration is removed from audio requests; a supported duration field must be supplied through the model’s declared dynamic parameters.

Request the platform quote with the same body:

curl --fail --silent --show-error \
  --request POST \
  "${SFX_BASE_URL}/api/ai/router01/quote" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

For a successful quote, inspect data.credits. The quote does not create a generation. Confirm the cost with your user before submitting; the server recalculates the generation price rather than trusting a client-supplied amount.

Submit a platform generation

The following request creates a task and can consume account credits:

curl --fail --silent --show-error \
  --request POST \
  "${SFX_BASE_URL}/api/ai/generate" \
  --header "Authorization: Bearer ${SFX_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

On success, the JSON response includes data.id, data.taskId, data.taskStatus, data.costCredits and data.remainingBalance. Keep the local data.id to query the same task. The initial status is queued; this response is not an audio file and should not be saved as an MP3.

No generation idempotency key is documented here. If a POST times out, inspect existing tasks or creations before submitting another one. A repeat submission can create another separately billed task.

Poll and retrieve the result

Set SFX_TASK_ID to the local ID returned by your successful submission:

curl --fail --silent --show-error \
  "${SFX_BASE_URL}/api/ai/task?taskId=${SFX_TASK_ID}" \
  --header "Authorization: Bearer ${SFX_API_KEY}"

Continue polling the same ID with a bounded wait and increasing intervals while data.taskStatus is queued, pending or processing. Stop for success, failed or canceled.

On successful audio tasks, the normalized response exposes audio URLs in data.taskInfo.songs[].audioUrl. The songs field is the platform’s existing audio container; it does not mean the content must be music. Download the returned file as a separate step and inspect its actual format. For a failed or canceled task, inspect data.taskInfo.userErrorCode instead of assuming an output URL exists.

Handle errors and budget

The platform wraps data as JSON: code: 0 indicates success; code: -1 indicates an application error with a message. Check this even when HTTP status is 200. An HTTP failure also needs handling; use the response message where appropriate.

An unsupported model or option calls for correcting input, not blind retries. Invalid credentials require checking the correct account and host. For busy services, back off rather than resubmitting in a tight loop. Completed outputs you choose not to use are different from failed tasks; see pricing, the Terms and troubleshooting.