> ## 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.

# Create Song

> Generate a new song asynchronously

Create a new song with a text prompt (simple mode) or detailed controls (advanced mode). The song is generated asynchronously — the response returns immediately with a pending song ID that you can poll for status.

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key
</ParamField>

<ParamField header="Content-Type" type="string" required>
  application/json (or multipart/form-data if uploading lyrics\_file)
</ParamField>

### Body

<ParamField body="mode" type="string" default="advanced">
  `simple` or `advanced`. Simple: one-line description, we write lyrics. Advanced: full control.
</ParamField>

<ParamField body="prompt" type="string" required>
  1–2000 characters. Simple mode: song description. Advanced mode: musical style (genre, mood, instruments, BPM).
</ParamField>

<ParamField body="lyrics" type="string">
  Your own lyrics (≤12000 chars). Optional `[Verse]`/`[Chorus]` section tags allowed. Advanced mode only; exactly one lyrics source.
</ParamField>

<ParamField body="lyrics_prompt" type="string">
  Generate lyrics from a description (≤2000 chars). E.g., "Write about summer freedom". Advanced mode only; exactly one lyrics source.
</ParamField>

<ParamField body="lyrics_file" type="file">
  Multipart upload of a .txt file (≤64 KB). Advanced mode only; exactly one lyrics source.
</ParamField>

<ParamField body="instrumental" type="boolean" default="false">
  If true, song has no vocals; `[Instrumental]` tag is sent automatically. Allows skipping lyrics in advanced mode.
</ParamField>

<ParamField body="vocal_gender" type="string">
  `Male` or `Female`. Optional.
</ParamField>

<ParamField body="voice_id" type="string" default="">
  From `GET /songs/voices`: catalog voice or saved voice owned by your workspace. Optional.
</ParamField>

<ParamField body="negative_tags" type="string">
  Styles to exclude (≤1000 chars). Optional.
</ParamField>

<ParamField body="tags" type="string">
  Extra style tags (≤1000 chars). Optional.
</ParamField>

<ParamField body="target_duration" type="integer">
  10–600 seconds. The model treats it as a hint. Optional.
</ParamField>

<ParamField body="seed" type="string">
  Digit string (≤19 digits, ≤2^63-1) for repeatable results. Must be a string, not a number. Optional.
</ParamField>

<ParamField body="title" type="string">
  Display title (≤200 chars). If omitted, a title is auto-generated from lyrics. Optional.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always true on 201
</ResponseField>

<ResponseField name="message" type="string">
  "Your song is being created"
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="batch_id" type="string">
      UUID grouping one or more songs
    </ResponseField>

    <ResponseField name="songs" type="array">
      Array with one Song object (status: "submitted" initially)
    </ResponseField>

    <ResponseField name="warnings" type="array">
      Optional validation warnings
    </ResponseField>
  </Expandable>
</ResponseField>

**Song Object:**

```
id (uuid), batch_id (uuid), variant_index (int), status (submitted|running|succeeded|failed),
progress (string|null, e.g. "writing lyrics"), mode, title (string|null), prompt, tags,
instrumental (bool), vocal_gender, voice_id, duration_seconds (null until ready), audio_url (null until ready),
liked (bool), played (bool), error_message (null unless failed), created_at, completed_at
```

## Errors

| Status  | Code                     | Meaning                                                                  |
| ------- | ------------------------ | ------------------------------------------------------------------------ |
| 400     | Validation error         | Invalid prompt, missing field, or both `lyrics` and `lyrics_prompt` sent |
| 403     | `VOICE_NOT_ACCESSIBLE`   | The voice ID isn't usable by your workspace                              |
| 409     | `GENERATION_IN_PROGRESS` | A song is already being generated; try again in 2 minutes                |
| 429     | Rate limited             | Too many requests                                                        |
| 502/503 | Service unavailable      | Temporary outage                                                         |

## Example

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

  ```javascript JavaScript theme={null}
  const song = await client.music.create({
    mode: 'simple',
    prompt: 'upbeat lo-fi hip hop with jazzy chords'
  });
  console.log('Song ID:', song.data.songs[0].id);
  ```

  ```python Python theme={null}
  song = client.music.create(
      mode='simple',
      prompt='upbeat lo-fi hip hop with jazzy chords'
  )
  print('Song ID:', song['data']['songs'][0]['id'])
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Your song is being created",
    "data": {
      "batch_id": "550e8400-e29b-41d4-a716-446655440000",
      "songs": [
        {
          "id": "song-550e8400-e29b-41d4-a716-446655440001",
          "batch_id": "550e8400-e29b-41d4-a716-446655440000",
          "variant_index": 0,
          "status": "submitted",
          "progress": null,
          "mode": "simple",
          "title": null,
          "prompt": "upbeat lo-fi hip hop with jazzy chords",
          "tags": null,
          "instrumental": false,
          "vocal_gender": null,
          "voice_id": null,
          "duration_seconds": null,
          "audio_url": null,
          "liked": false,
          "played": false,
          "error_message": null,
          "created_at": "2026-09-24T10:30:00Z",
          "completed_at": null
        }
      ],
      "warnings": []
    }
  }
  ```
</ResponseExample>