# Music

ShortGenius also provides an AI-curated music catalog to serve as background tracks for your videos. You can explore various genres and pick specific tracks to add life to your video content.

## List Music Genres

**Endpoint**: `GET /music/genres`

Retrieve the full list of available music genres. Each genre may include recommended locales where that genre is particularly popular.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { ShortGenius } from 'shortgenius'

const client = new ShortGenius({
  bearerAuth: 'YOUR_API_TOKEN'
})

const genres = await client.getMusicGenres()

console.log(`Found ${genres.length} music genres:`)

for (const genre of genres) {
  console.log(`- ${genre.name}`)
  if (genre.recommended_for_locales && genre.recommended_for_locales.length > 0) {
    console.log(`  Recommended for: ${genre.recommended_for_locales.join(', ')}`)
  }
}
```

{% endtab %}

{% tab title="Python" %}

```python
from shortgenius import Shortgenius

client = Shortgenius(api_key="YOUR_API_TOKEN")

genres = client.music.genres.list()

print(f"Found {len(genres)} music genres:")

for genre in genres:
    print(f"- {genre.name}")
    if genre.recommended_for_locales:
        print(f"  Recommended for: {', '.join(genre.recommended_for_locales)}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://shortgenius.com/api/v1/music/genres" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

**Sample Response**:

```json
[
  {
    "name": "Classical",
    "recommended_for_locales": [
      "de-DE",
      "fr-FR",
      "en-US"
    ]
  },
  {
    "name": "Jazz",
    "recommended_for_locales": [
      "en-US",
      "fr-FR"
    ]
  },
  ...
]
```

### Response Fields

| Field                     | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `name`                    | The name of the genre (e.g., `"Classical"`).              |
| `recommended_for_locales` | Array of locales where the genre is particularly popular. |

***

## List Music in a Genre

**Endpoint**: `GET /music/genres/{id}`

Use the **genre's name** or **unique ID** returned by `GET /music/genres` to list specific tracks.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// First get genres to find the ID
const genres = await client.getMusicGenres()
const classicalGenre = genres.find(g => g.name === 'Classical')

if (classicalGenre) {
  const tracks = await client.getMusic(classicalGenre.id)

  console.log(`Found ${tracks.length} tracks in ${classicalGenre.name}:`)

  for (const track of tracks) {
    console.log(`- ${track.name} (${track.id})`)
    if (track.preview_url) {
      console.log(`  Preview: ${track.preview_url}`)
    }
  }
}
```

{% endtab %}

{% tab title="Python" %}

```python
# First get genres to find the ID
genres = client.music.genres.list()
classical_genre = next((g for g in genres if g.name == "Classical"), None)

if classical_genre:
    tracks = client.music.tracks.list(genre_id=classical_genre.id)

    print(f"Found {len(tracks)} tracks in {classical_genre.name}:")

    for track in tracks:
        print(f"- {track.name} ({track.id})")
        if track.preview_url:
            print(f"  Preview: {track.preview_url}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://shortgenius.com/api/v1/music/genres/Classical" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

**Sample Response**:

```json
[
  {
    "id": "73f3cd22-bd13-4ec1-a675-82de290c598f",
    "name": "Moonlight Sonata (Excerpt)",
    "preview_url": "https://cdn.shortgenius.com/music/73f3cd22-preview.mp3"
  },
  {
    "id": "ee13c403-6503-49c4-9ff8-a9a45eb558bb",
    "name": "Fur Elise (Excerpt)",
    "preview_url": "https://cdn.shortgenius.com/music/ee13c403-preview.mp3"
  },
  ...
]
```

### Response Fields

| Field         | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| `id`          | Unique ID of the track (for use in `/videos` or `/series`). |
| `name`        | Track title (may be partial or excerpt).                    |
| `preview_url` | Direct link to a short preview audio clip of the track.     |

***

## Using Music in Videos

After identifying a suitable track's `id`, simply include it in your request to **create** or **update** a video:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// Get a soundtrack
const genres = await client.getMusicGenres()
const tracks = await client.getMusic(genres[0].id)

// Use in video creation
const video = await client.createVideo({
  // ... other video fields ...
  soundtrack_id: tracks[0].id,
  soundtrack_volume: 80,
  soundtrack_playback_rate: 120
})

console.log(`Video created with soundtrack: ${tracks[0].name}`)
```

{% endtab %}

{% tab title="Python" %}

```python
# Get a soundtrack
genres = client.music.genres.list()
tracks = client.music.tracks.list(genre_id=genres[0].id)

# Use in video creation
video = client.videos.create(
    # ... other video fields ...
    soundtrack_id=tracks[0].id,
    soundtrack_volume=80,
    soundtrack_playback_rate=120
)

print(f"Video created with soundtrack: {tracks[0].name}")
```

{% endtab %}

{% tab title="JSON" %}

```json
{
  "soundtrack_id": "73f3cd22-bd13-4ec1-a675-82de290c598f",
  "soundtrack_volume": 80,
  "soundtrack_playback_rate": 120
}
```

{% endtab %}
{% endtabs %}

ShortGenius will overlay this music behind your AI-generated voice and scenes, producing a fully scored video.

***

## Next Steps

Now that you can add background music:

1. Check out [Connections & Publishing](https://shortgenius.gitbook.io/api/guides/music) to learn how to publish your videos.
2. Monitor your [Usage & Credits](https://shortgenius.gitbook.io/api/guides/music) so you always have enough resources to generate new music-backed projects.