Interface GenerateMusicOptions

Options for a generateMusic call.

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

interface GenerateMusicOptions {
    prompt: string;
    provider?: string;
    model?: string;
    durationSec?: number;
    negativePrompt?: string;
    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? negativePrompt? outputFormat? seed? timeoutMs? n? onProgress? apiKey? userId? providerOptions? providerPreferences? usageLedger?

Properties

prompt

prompt: string

Text prompt describing the desired musical composition.

Optional provider

provider?: string

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

Optional model

model?: string

Model identifier within the provider (e.g. "suno-v3.5", "stable-audio-open-1.0"). When omitted, the provider's default model is used.

Optional durationSec

durationSec?: number

Desired output duration in seconds. Provider limits vary.

Optional negativePrompt

negativePrompt?: string

Negative prompt describing musical elements to avoid.

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

promptprovidermodeldurationSecnegativePromptoutputFormatseedtimeoutMsnonProgressapiKeyuserIdproviderOptionsproviderPreferencesusageLedger