> ## Documentation Index
> Fetch the complete documentation index at: https://docs.60db.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Music Generation

> Generate high-quality music with AI, using simple text prompts or advanced controls

## Overview

60db's **Music** API lets you generate original songs, with vocals or instrumental, in about two minutes. Describe your song in simple English (genre, mood, instruments) or fine-tune every aspect with advanced mode: custom lyrics, vocal gender, duration target, style tags, and seed-based repeatability.

Every workspace generates **one song at a time** — while a generation runs, new requests return a **429 Too Many Requests** error. Most songs take **1.5–2.5 minutes** to create.

<CardGroup cols={2}>
  <Card title="Simple Mode" icon="zap">
    Describe your song in one line; we'll write the lyrics for you
  </Card>

  <Card title="Advanced Mode" icon="sliders">
    Full control: your lyrics, vocal gender, instrumentation, BPM, duration
  </Card>

  <Card title="Voice Library" icon="microphone">
    Catalog voices or your own saved voices
  </Card>

  <Card title="Seed Repeatability" icon="repeat">
    Use a seed to regenerate the exact same song
  </Card>
</CardGroup>

## Quickstart

Generate your first song in three steps:

<Steps>
  <Step title="Create a song">
    Send a prompt and wait for generation to start.
  </Step>

  <Step title="Poll for completion">
    Check status every 3–5 seconds until the song is ready.
  </Step>

  <Step title="Download the MP3">
    Fetch the audio file once generation finishes.
  </Step>
</Steps>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # Step 1: Create a song
    curl -X POST https://api.60db.ai/songs \
      -H "Authorization: Bearer your-api-key" \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "upbeat lo-fi hip hop with jazzy chords",
        "mode": "simple"
      }'

    # Response: { "success": true, "data": { "batch_id": "xyz", "songs": [ { "id": "song-001", "status": "submitted" } ] } }

    # Step 2: Poll for completion (repeat every 3-5 seconds)
    curl https://api.60db.ai/songs/song-001 \
      -H "Authorization: Bearer your-api-key"

    # Wait for status === "succeeded"

    # Step 3: Download the MP3
    curl https://api.60db.ai/songs/song-001/download \
      -H "Authorization: Bearer your-api-key" \
      -o my-song.mp3
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { SixtyDBClient } from '60db';

    const client = new SixtyDBClient('your-api-key');

    // Step 1: Create a song
    const result = await client.music.create({
      prompt: 'upbeat lo-fi hip hop with jazzy chords',
      mode: 'simple'
    });
    const songId = result.data.songs[0].id;

    // Step 2: Wait for completion
    const song = await client.music.waitForCompletion(songId, {
      intervalMs: 4000,
      timeoutMs: 600000
    });

    // Step 3: Download
    const audioBuffer = await client.music.download(songId);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from sixtydb import SixtyDBClient

    client = SixtyDBClient('your-api-key')

    # Step 1: Create a song
    result = client.music.create(
        prompt='upbeat lo-fi hip hop with jazzy chords',
        mode='simple'
    )
    song_id = result['data']['songs'][0]['id']

    # Step 2: Wait for completion
    song = client.music.wait_for_completion(song_id, interval=4, timeout=600)

    # Step 3: Download
    audio_bytes = client.music.download(song_id)
    with open('my-song.mp3', 'wb') as f:
        f.write(audio_bytes)
    ```
  </Tab>
</Tabs>

## Simple vs Advanced Mode

### Simple Mode

Send a **one-line description** and we write the lyrics for you.

```bash theme={null}
curl -X POST https://api.60db.ai/songs \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "sad piano ballad about lost love",
    "mode": "simple"
  }'
```

In simple mode, your `prompt` becomes the musical style (genre, mood, instruments, BPM). We automatically generate lyrics that fit the vibe.

### Advanced Mode

Take full control of the output:

```bash theme={null}
curl -X POST https://api.60db.ai/songs \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Upbeat, indie rock with driving drums",
    "mode": "advanced",
    "lyrics": "[Verse]\nChasing shadows down the street\nLife is fast and oh so sweet",
    "vocal_gender": "Male",
    "voice_id": "vocal-001",
    "target_duration": 180,
    "tags": "electric guitar, pop-rock"
  }'
```

**Advanced mode requires exactly one lyrics source:**

* `lyrics` — your own lyrics (with optional `[Verse]` / `[Chorus]` tags)
* `lyrics_prompt` — describe what you want: "Write about summer freedom"
* `lyrics_file` — upload a `.txt` file
* `instrumental: true` — generate without vocals

## Lyrics Tips

### Section Tags

Organize your lyrics with `[Verse]` and `[Chorus]` tags:

```
[Verse]
Wake up in the morning light
Everything feels right

[Chorus]
This is our time
This is our time to shine

[Verse]
Dancing through the night
Stars are burning bright

[Chorus]
This is our time
This is our time to shine
```

The model respects these tags and places them appropriately in the music.

### Single Source Rule

In **advanced mode**, provide **exactly one** of:

* User-provided `lyrics`
* A `lyrics_prompt` ("describe your song idea")
* A `lyrics_file` (multipart upload)
* `instrumental: true` (no lyrics)

Sending both `lyrics` and `lyrics_prompt` returns a **400 Bad Request**. Simple mode fills `lyrics_prompt` automatically from `prompt`.

## Voice Library

Use a catalog voice or save your own custom voice from an audio sample:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // List available voices
    const voices = await client.music.listVoices();

    console.log('Catalog voices:', voices.data.catalog);
    console.log('My voices:', voices.data.mine);

    // Use a catalog voice
    await client.music.create({
      prompt: 'happy pop song',
      voice_id: 'vocal-001'  // from the catalog
    });

    // Save your own voice
    const voiceFile = document.querySelector('input[type="file"]').files[0];
    const newVoice = await client.music.createVoice({
      name: 'My Voice',
      file: voiceFile
    });

    // Use your saved voice
    await client.music.create({
      prompt: 'happy pop song',
      voice_id: newVoice.data.voice_id
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # List available voices
    voices = client.music.list_voices()

    print('Catalog voices:', voices['data']['catalog'])
    print('My voices:', voices['data']['mine'])

    # Use a catalog voice
    client.music.create(
        prompt='happy pop song',
        voice_id='vocal-001'  # from the catalog
    )

    # Save your own voice
    with open('my_voice_sample.wav', 'rb') as f:
        new_voice = client.music.create_voice(
            name='My Voice',
            file=f
        )

    # Use your saved voice
    client.music.create(
        prompt='happy pop song',
        voice_id=new_voice['data']['voice_id']
    )
    ```
  </Tab>
</Tabs>

**Catalog voices** include `preview_url` (a short sample clip). **Your saved voices** show `null` for `preview_url`.

## Limits & Constraints

| Constraint                   | Value                                                                |
| ---------------------------- | -------------------------------------------------------------------- |
| One generation per workspace | Only one song is generated at a time; concurrent requests return 429 |
| Prompt length                | 1–2000 characters                                                    |
| Lyrics length                | ≤ 12,000 characters                                                  |
| Song duration hint           | 10–600 seconds (the model treats it as a hint)                       |
| Voice sample length          | 3–30 seconds for custom voices                                       |
| Voice sample size            | ≤ 10 MB                                                              |
| Generation time              | \~1.5–2.5 minutes typical                                            |
| Audio URL lifetime           | \~1 hour (re-fetch the song to get a fresh signed URL)               |

## Pricing

**Music generation is free during beta.** No credits are charged, and no wallet deductions occur.

When we launch paid plans, pricing will be based on song length and quality tier.

## Error Handling

| Status | Code                     | Meaning                                                                           |
| ------ | ------------------------ | --------------------------------------------------------------------------------- |
| 400    | Validation error         | Invalid prompt, missing required field, or both `lyrics` and `lyrics_prompt` sent |
| 403    | `VOICE_NOT_ACCESSIBLE`   | The voice ID isn't usable by your workspace                                       |
| 404    | Not found                | Song ID doesn't exist or isn't in your workspace                                  |
| 409    | `GENERATION_IN_PROGRESS` | A song is already being generated in your workspace; try again in 2 minutes       |
| 429    | Too many requests        | Rate limited (only applies to non-async endpoints)                                |
| 502    | Service unavailable      | The music service is temporarily down                                             |
| 503    | Service unavailable      | The music service is temporarily down                                             |

## API Reference

<CardGroup cols={2}>
  <Card title="Create Song" icon="plus" href="/api-reference/music/create-song">
    Generate a new song
  </Card>

  <Card title="List Songs" icon="list" href="/api-reference/music/list-songs">
    Get your song library
  </Card>

  <Card title="Get Song" icon="circle-info" href="/api-reference/music/get-song">
    Poll status or fetch details
  </Card>

  <Card title="Update Song" icon="pen" href="/api-reference/music/update-song">
    Mark liked or played
  </Card>

  <Card title="Download Song" icon="download" href="/api-reference/music/download-song">
    Get the MP3 file
  </Card>

  <Card title="Delete Song" icon="trash" href="/api-reference/music/delete-song">
    Move to trash
  </Card>

  <Card title="List Voices" icon="microphone" href="/api-reference/music/list-voices">
    Browse available voices
  </Card>

  <Card title="Create Voice" icon="microphone" href="/api-reference/music/create-voice">
    Save a custom voice
  </Card>

  <Card title="Health Check" icon="heart-pulse" href="/api-reference/music/health">
    Service status
  </Card>
</CardGroup>