# 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://api.shortgenius.com/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://api.shortgenius.com/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](/api/guides/publishing.md) to learn how to publish your videos.
2. Monitor your [Usage & Credits](/api/guides/music.md) so you always have enough resources to generate new music-backed projects.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shortgenius.gitbook.io/api/guides/music.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.