Interface: GenerateMusicOptions

Defined in: packages/agentos/src/api/generateMusic.ts:209

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).

Properties

apiKey?

optional apiKey: string

Defined in: packages/agentos/src/api/generateMusic.ts:254

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

---

durationSec?

optional durationSec: number

Defined in: packages/agentos/src/api/generateMusic.ts:227

Desired output duration in seconds. Provider limits vary.

---

model?

optional model: string

Defined in: packages/agentos/src/api/generateMusic.ts:224

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

---

n?

optional n: number

Defined in: packages/agentos/src/api/generateMusic.ts:245

Number of audio clips to generate. Defaults to 1.

---

negativePrompt?

optional negativePrompt: string

Defined in: packages/agentos/src/api/generateMusic.ts:230

Negative prompt describing musical elements to avoid.

---

onProgress()?

optional onProgress: (event) => void

Defined in: packages/agentos/src/api/generateMusic.ts:251

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

Parameters

event

AudioProgressEvent

Returns

void

---

outputFormat?

optional outputFormat: AudioOutputFormat

Defined in: packages/agentos/src/api/generateMusic.ts:233

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

---

prompt

prompt: string

Defined in: packages/agentos/src/api/generateMusic.ts:211

Text prompt describing the desired musical composition.

---

provider?

optional provider: string

Defined in: packages/agentos/src/api/generateMusic.ts:217

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

---

providerOptions?

optional providerOptions: Record<string, unknown>

Defined in: packages/agentos/src/api/generateMusic.ts:260

Arbitrary provider-specific options.

---

providerPreferences?

optional providerPreferences: MediaProviderPreference

Defined in: packages/agentos/src/api/generateMusic.ts:267

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.

---

seed?

optional seed: number

Defined in: packages/agentos/src/api/generateMusic.ts:236

Random seed for reproducible generation (provider-dependent).

---

timeoutMs?

optional timeoutMs: number

Defined in: packages/agentos/src/api/generateMusic.ts:242

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

---

usageLedger?

optional usageLedger: AgentOSUsageLedgerOptions

Defined in: packages/agentos/src/api/generateMusic.ts:270

Optional durable usage ledger configuration for accounting.

---

userId?

optional userId: string

Defined in: packages/agentos/src/api/generateMusic.ts:257

Optional user identifier forwarded to the provider for billing.