API Documentation — resonant4music.ai

Base URL

https://resonant4music.ai/api/v1

Generate Music

Submit a generation job. Returns a job ID for polling.

POST /generate

Request Body

Parameter	Type	Description
`prompt`	string	Text description of desired music (e.g. "tense chase scene"). Either prompt or params required.
`params`	object	Direct geometry parameters (see below). Either prompt or params required.
`duration_seconds`	float	Duration in seconds (1–300). Default: 30
`tempo`	float	BPM (40–300). Default: 120
`format`	string	`wav`, `mp3`, or `midi`. Default: wav

Geometry Parameters

Parameter	Type	Range	Description
`n`	int	2–2000	Complexity — number of geometric elements
`k`	int	1–n/2	Texture — step size controlling interval structure
`omega`	float	-10 to 10	Movement — rotation speed of the geometry
`xi`	float	-10 to 10	Depth — vertical perturbation
`psi`	float	0 to 2π	Phase — shifts the tonal center
`lock_psi_tau`	bool	—	Lock phase to tempo grid for rhythmic patterns

Example — Text Prompt

curl -X POST https://resonant4music.ai/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "jazzy late night café",
    "duration_seconds": 30,
    "format": "mp3"
  }'

# Response
{
  "job_id": "a3f8c2e91b04",
  "status": "pending"
}
        

Example — Direct Parameters

curl -X POST https://resonant4music.ai/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "params": {"n": 120, "k": 49, "omega": 2.5, "xi": 1.8},
    "duration_seconds": 30
  }'
        

Check Job Status

Poll for generation completion. Jobs typically complete in a few seconds.

GET /jobs/{job_id}

Response

{
  "job_id": "a3f8c2e91b04",
  "status": "complete",
  "download_url": "/api/v1/jobs/a3f8c2e91b04/download"
}
        

Status values: pending → processing → complete | failed

Download Audio

GET /jobs/{job_id}/download

Returns the generated audio file. Content-Type matches the requested format.

Quick Preview

Synchronous generation of a short (5s) preview clip. Returns audio directly — no job polling needed.

POST /preview

Example

curl -X POST https://resonant4music.ai/api/v1/preview \
  -H "Content-Type: application/json" \
  -d '{"prompt": "calm piano"}' \
  --output preview.wav
        

List Presets

Get all available curated presets — moods, genres, and scenes mapped to optimized geometry parameters.

GET /presets

Response

{
  "presets": [
    {
      "id": "calm",
      "name": "Calm",
      "description": "Gentle, meditative tones...",
      "tags": ["peaceful", "meditation", "ambient"]
    },
    ...
  ]
}
        

60+ presets covering moods, genres, scenes, and experimental textures.

Error Handling

Errors return standard HTTP status codes with a JSON body:

{
  "detail": "Provide either 'prompt' or 'params'"
}
        

Status	Meaning
`400`	Bad request — missing or invalid parameters
`404`	Job not found
`409`	Job not yet complete (for download endpoint)
`422`	Validation error — parameter out of range

Tips

Text prompts are resolved to geometry parameters via semantic matching. Descriptive prompts work best: "tense chase through neon streets" outperforms "fast music".
Trajectories: Prompts with transition words ("building to", "shifting from...to") create parameter trajectories that evolve over time.
Deterministic: Same parameters + same duration = identical output. Cache freely.
Duration: Longer files take proportionally longer to generate. 30s is typical; 300s max.
MIDI: For maximum flexibility, request MIDI format and use your own instruments/DAW.