Interface GenerateSFXOptions

Options for a generateSFX call.

At minimum, a prompt is required. The provider is resolved from opts.provider, opts.apiKey, or the first SFX-capable env var found (ELEVENLABS_API_KEY -> STABILITY_API_KEY -> REPLICATE_API_TOKEN -> FAL_API_KEY -> local AudioGen).

interface GenerateSFXOptions {
    prompt: string;
    provider?: string;
    model?: string;
    durationSec?: number;
    outputFormat?: AudioOutputFormat;
    seed?: number;
    timeoutMs?: number;
    n?: number;
    onProgress?: ((event) => void);
    apiKey?: string;
    userId?: string;
    providerOptions?: Record<string, unknown>;
    providerPreferences?: MediaProviderPreference;
    usageLedger?: AgentOSUsageLedgerOptions;
}

Properties

prompt provider? model? durationSec? outputFormat? seed? timeoutMs? n? onProgress? apiKey? userId? providerOptions? providerPreferences? usageLedger?

Properties

prompt

prompt: string

Text prompt describing the desired sound effect.

Optional provider

provider?: string

Explicit provider identifier (e.g. "elevenlabs-sfx", "stable-audio", "audiogen-local"). When omitted, auto-detection from environment variables is used.

Optional model

model?: string

Model identifier within the provider. When omitted, the provider's default model is used.

Optional durationSec

durationSec?: number

Desired output duration in seconds. SFX clips are typically 1-15s.

Optional outputFormat

outputFormat?: AudioOutputFormat

Output audio format (e.g. "mp3", "wav"). Defaults to provider default.

Optional seed

seed?: number

Random seed for reproducible generation (provider-dependent).

Optional timeoutMs

timeoutMs?: number

Maximum time in milliseconds to wait for generation to complete. Provider-dependent — polling providers enforce this directly.

Optional n

n?: number

Number of audio clips to generate. Defaults to 1.

Optional onProgress

onProgress?: ((event) => void)

Optional progress callback invoked during long-running generation. Called with an AudioProgressEvent at each status transition.

Type declaration

Optional apiKey

apiKey?: string

Override the provider API key instead of reading from env vars.

Optional userId

userId?: string

Optional user identifier forwarded to the provider for billing.

Optional providerOptions

providerOptions?: Record<string, unknown>

Arbitrary provider-specific options.

Optional providerPreferences

providerPreferences?: MediaProviderPreference

Provider preferences for reordering or filtering the fallback chain. When supplied, the available providers are reordered according to preferred and filtered by blocked before building the chain.

Optional usageLedger

usageLedger?: AgentOSUsageLedgerOptions

Optional durable usage ledger configuration for accounting.

Settings

Member Visibility

Theme

On This Page

promptprovidermodeldurationSecoutputFormatseedtimeoutMsnonProgressapiKeyuserIdproviderOptionsproviderPreferencesusageLedger