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"
}
FieldTypeRequiredDescription
modelstringyesMusic model ID from GET /api/v1/music/models
promptstringyesStyle/caption description of the music (genre, mood, instrumentation)
task_typestringnoJob kind (see below); defaults to text2music
durationintegernoTarget duration in seconds (per-model min/max; default 180)
nintegernoNumber of tracks to generate (1..max_n, default 1)
lyricsstringnoLyrics for a sung song; omit for instrumental music
vocal_languagestringnoLanguage code for the vocals (e.g. en, zh, ja)
bpmintegernoTempo in beats per minute
key_scalestringnoMusical key (e.g. C major, A minor)
time_signaturestringnoTime signature (e.g. 4)
formatstringnoOutput audio format: mp3 (default), wav, flac, opus, or aac
seedintegernoSeed for deterministic generation
thinkingbooleannoLet the model plan the arrangement before rendering (default true)
use_formatbooleannoTreat prompt as a structured style/caption format (default false)
reference_artifact_idstringnoArtifact ID of a reference audio file in your account (for cover and style transfer)
src_artifact_idstringnoArtifact ID of the source audio to edit (for repaint, lego, extract, complete)

task_type selects the kind of job:

Task typeWhat it does
text2musicGenerate music from the prompt (default)
coverGenerate a cover from a reference track
repaintRegenerate a section of a track
legoGenerate a single instrument stem from the prompt
extractExtract a stem from a mixed track
completeComplete 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 }
}
StatusDescription
pendingThe job is queued
in_progressThe music is being generated
completedThe track(s) are ready to download
failedGeneration failed (see error); the reservation is fully refunded
cancelledThe job was cancelled; fully refunded
expiredThe 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

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.