Create a track · Docs

POSThttps://api.vaelor.chat/v1/music

Composes a full track — vocals and instruments, or instrumental only — from a description and optional lyrics. Rendering takes one to several minutes, so the response is an NDJSON event stream that ends with the finished track.

Body#

requestIduuidRequired

A UUID you generate for this track. Retrying with the same ID never creates or bills a second track. See Idempotency.

configurationobjectRequired

What to compose.

modeenumRequired

simple composes from description alone. custom uses every field you set.

descriptionstringRequired

The song in your own words, 1–2,000 characters.

durationintegerRequired

Length in seconds, from 30 to 500.

languageenumRequired

Vocal language as an ISO code, such as en, es, ja or pt. 20 languages are supported.

instrumentalbooleanRequired

Set to true for no vocals.

titlestring

Track title, up to 120 characters. Generated if empty.

lyricsstring

Lyrics with optional section tags like [Verse] and [Chorus], up to 8,000 characters.

genrestring

For example synthwave or bossa nova. Up to 120 characters.

moodstring

For example melancholic, hopeful. Up to 120 characters.

instrumentsstring

Comma-separated, up to 400 characters.

vocalStylestring

For example breathy female alto. Up to 120 characters.

keystring

Musical key, such as F# minor.

bpminteger

Tempo from 30 to 300.

negativePromptstring

Things to avoid, up to 2,000 characters.

guidanceScalenumberRequired

How closely to follow the prompt, from 1 to 20. Around 7 works well.

thinkbooleanRequired

Let the composer plan the song structure before rendering. Slower, often better.

seedinteger

Fix the seed to reproduce a result.

Response#

An application/x-ndjson stream of heartbeat, stage, complete and error events. The complete event carries the finished track and your remaining balance.

Example#

curl -N https://api.vaelor.chat/v1/music \
  -H "Authorization: Bearer $VAELOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "configuration": {
      "mode": "custom",
      "title": "Harbor Lights",
      "description": "A late-night synthwave drive along the coast",
      "genre": "synthwave",
      "mood": "nostalgic, warm",
      "duration": 180,
      "language": "en",
      "instrumental": true,
      "bpm": 96,
      "guidanceScale": 7,
      "think": true
    }
  }'

const response = await fetch('https://api.vaelor.chat/v1/music', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VAELOR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    requestId: crypto.randomUUID(),
    configuration: {
      mode: 'custom',
      title: 'Harbor Lights',
      description: 'A late-night synthwave drive along the coast',
      genre: 'synthwave',
      mood: 'nostalgic, warm',
      duration: 180,
      language: 'en',
      instrumental: true,
      bpm: 96,
      guidanceScale: 7,
      think: true
    }
  })
})

import uuid

response = requests.post(
    "https://api.vaelor.chat/v1/music",
    headers={"Authorization": f"Bearer {os.environ['VAELOR_API_KEY']}"},
    json={
        "requestId": str(uuid.uuid4()),
        "configuration": {
            "mode": "custom",
            "title": "Harbor Lights",
            "description": "A late-night synthwave drive along the coast",
            "genre": "synthwave",
            "mood": "nostalgic, warm",
            "duration": 180,
            "language": "en",
            "instrumental": True,
            "bpm": 96,
            "guidanceScale": 7,
            "think": True,
        },
    },
    stream=True,
)

Response200

JSON

{"type":"stage","message":"Composing your track. This may take a few minutes…"}
{"type":"heartbeat"}
{"type":"stage","message":"Saving your song…"}
{"type":"complete","track":{"id":"5f0c2d1e-7a39-4b8e-9e61-2d4f8a0b3c77","status":"ready","title":"Harbor Lights","durationSeconds":180,"creditCost":180},"usageRemaining":420}

Billing#

The cost is duration × 1 credit, reserved in full before rendering starts. If rendering fails you get an error event and the credits are refunded.

Errors#

Status	When
`400`	The configuration failed validation, or the combined prompt exceeds 2,000 characters.
`402`	Not enough credits for the requested duration.
`409`	`DUPLICATE_REQUEST` — a track already exists for this `requestId`.
`503`	Music generation is temporarily unavailable.