Music

Perceptron provides a music generation API. Music models accept a text prompt (and optional reference audio for covers, remixes, and edits) and generate one or more audio tracks.

Music generation is asynchronous: you submit a job, poll its status, and download the finished track(s). Generation typically takes one to several minutes depending on the length and model.

Base URL

https://perceptron.cloud/api/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Available Models

curl https://perceptron.cloud/api/v1/music/models

Each model reports its capabilities: min_duration / max_duration (seconds), supports_lyrics, supports_instrumental, supports_reference_audio, max_n (tracks per job), task_types, and per-second pricing under pricing.music.per_second.

Generating Music

1. Submit a job

POST /api/v1/music

curl -X POST https://perceptron.cloud/api/v1/music \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ace-step/ace-step-v1.5-xl",
    "prompt": "warm indie folk, fingerpicked guitar, brushed drums, mellow",
    "lyrics": "[Verse] Morning light across the floor\n[Chorus] We are on our way",
    "duration": 120,
    "n": 1,
    "format": "mp3"
  }'

Returns 202 Accepted with the job details:

{
  "id": "0e1b0c3f-...",
  "polling_url": "/api/v1/music/0e1b0c3f-...",
  "status": "pending"
}

Field	Type	Required	Description
`model`	string	yes	Music model ID from `GET /api/v1/music/models`
`prompt`	string	yes	Style/caption description of the music (genre, mood, instrumentation)
`task_type`	string	no	Job kind (see below); defaults to `text2music`
`duration`	integer	no	Target duration in seconds (per-model min/max; default `180`)
`n`	integer	no	Number of tracks to generate (`1`..`max_n`, default `1`)
`lyrics`	string	no	Lyrics for a sung song; omit for instrumental music
`vocal_language`	string	no	Language code for the vocals (e.g. `en`, `zh`, `ja`)
`bpm`	integer	no	Tempo in beats per minute
`key_scale`	string	no	Musical key (e.g. `C major`, `A minor`)
`time_signature`	string	no	Time signature (e.g. `4`)
`format`	string	no	Output audio format: `mp3` (default), `wav`, `flac`, `opus`, or `aac`
`seed`	integer	no	Seed for deterministic generation
`thinking`	boolean	no	Let the model plan the arrangement before rendering (default `true`)
`use_format`	boolean	no	Treat `prompt` as a structured style/caption format (default `false`)
`reference_artifact_id`	string	no	Artifact ID of a reference audio file in your account (for `cover` and style transfer)
`src_artifact_id`	string	no	Artifact ID of the source audio to edit (for `repaint`, `lego`, `extract`, `complete`)

task_type selects the kind of job:

Task type	What it does
`text2music`	Generate music from the prompt (default)
`cover`	Generate a cover from a reference track
`repaint`	Regenerate a section of a track
`lego`	Generate a single instrument stem from the prompt
`extract`	Extract a stem from a mixed track
`complete`	Complete or extend a partial track

Reference and source audio are supplied as artifact IDs from your account (upload the audio to your artifact library first), not inline audio bytes. Audio-input task types require the model to declare supports_reference_audio.

2. Poll for status

GET /api/v1/music/{id}

curl https://perceptron.cloud/api/v1/music/0e1b0c3f-... \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY"

{
  "id": "0e1b0c3f-...",
  "polling_url": "/api/v1/music/0e1b0c3f-...",
  "status": "completed",
  "unsigned_urls": ["/api/v1/music/0e1b0c3f-.../content?index=0"],
  "usage": { "cost": 0.08 }
}

Status	Description
`pending`	The job is queued
`in_progress`	The music is being generated
`completed`	The track(s) are ready to download
`failed`	Generation failed (see `error`); the reservation is fully refunded
`cancelled`	The job was cancelled; fully refunded
`expired`	The job exceeded its generation time limit; fully refunded

Poll at a reasonable interval (e.g. every 5–30 seconds). When n > 1, unsigned_urls contains one entry per track.

3. Download a track

GET /api/v1/music/{id}/content?index=N

curl https://perceptron.cloud/api/v1/music/0e1b0c3f-.../content?index=0 \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY" \
  --output track.mp3

Raw audio bytes with a Content-Type matching the requested format (e.g. audio/mpeg, audio/wav, audio/flac). index is 0-based. Finished tracks are stored as artifacts in your account.

Listing and deleting jobs

GET /api/v1/music: list your music generation jobs, newest first.
DELETE /api/v1/music/{id}: delete a job and its stored tracks, stopping their storage billing. In-flight jobs are cancelled and refunded.

See the full reference at API Reference.

Pricing

Music generation is billed per output second from your credits balance. The full quoted cost (duration × rate × n) is reserved at submit time and settled at the actual returned durations; failed jobs are fully refunded. See the live per-model rates at GET /api/v1/music/models, and Billing for more details.

Mining

Music requests can be served by Perceptron’s peer compute network. Include "miners": true in the request body to prefer a miner, or "use_my_nodes": true to run on your own registered nodes. See Mining.

Mined requests can also be steered: node pins one node id, miner pins one miner (any of that account’s nodes), and node_blacklist / miner_blacklist are arrays of ids to exclude. Ids are the public node_id / miner_id values from GET /api/mining/nodes. A pinned target that cannot serve the request fails rather than routing elsewhere, and responses report the serving target in usage.node_id / usage.miner_id.

Studio

The Perceptron app includes Perceptron Studio, a creative studio interface for generating and managing music without writing any code: open the app and select Studio in the sidebar menu.