Colonne sonore
GET /3/movie/{movie_id}/soundtracks e GET /3/tv/{tv_id}/soundtracks restituiscono l'album della colonna sonora di un titolo in una lista results. Ogni album ha source, nome, artista, data di uscita, link e una lista tracks con disco, numero, titolo, artista e durata. Aggiungi append_to_response=soundtracks per unirla ai dettagli.
Ottenere la colonna sonora di un film
GET / restituisce l'album della colonna sonora di un film. La risposta contiene l'id del film e un array results. Ogni voce è un album con i suoi dettagli e una lista tracks.
L'esempio carica The Dark Knight (id 155) e stampa l'album e una riga per brano.
curl -sf "https://api.amodb.dev/3/movie/155/soundtracks" \
-H "Authorization: Bearer $AMODB_KEY"const res = await fetch('https://api.amodb.dev/3/movie/155/soundtracks', {
headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results } = await res.json();
if (results.length === 0) console.log('no soundtrack album known');
for (const album of results) {
console.log(`${album.album} by ${album.artist} (${album.track_count} tracks)`);
for (const t of album.tracks) {
console.log(`${t.number}. ${t.title} by ${t.artist}`);
}
}import os
import requests
r = requests.get(
"https://api.amodb.dev/3/movie/155/soundtracks",
headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
timeout=10,
)
r.raise_for_status()
results = r.json()["results"]
if not results:
print("no soundtrack album known")
for album in results:
print(f"{album['album']} by {album['artist']} ({album['track_count']} tracks)")
for t in album["tracks"]:
print(f"{t['number']}. {t['title']} by {t['artist']}")<?php
$ch = curl_init('https://api.amodb.dev/3/movie/155/soundtracks');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("amodb returned $status");
}
$results = json_decode($body, true)['results'];
if (!$results) {
echo 'no soundtrack album known', PHP_EOL;
}
foreach ($results as $album) {
echo $album['album'], ' by ', $album['artist'] ?? 'unknown', ' (', $album['track_count'], ' tracks)', PHP_EOL;
foreach ($album['tracks'] as $t) {
echo $t['number'], '. ', $t['title'], ' by ', $t['artist'], PHP_EOL;
}
}package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
type Track struct {
Disc int `json:"disc"`
Number int `json:"number"`
Title string `json:"title"`
Artist string `json:"artist"`
DurationMs int `json:"duration_ms"`
}
type Album struct {
Source string `json:"source"`
Album string `json:"album"`
Artist string `json:"artist"`
Released string `json:"released"`
URL string `json:"url"`
TrackCount int `json:"track_count"`
Tracks []Track `json:"tracks"`
}
func main() {
req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/155/soundtracks", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
client := &http.Client{Timeout: 10 * time.Second}
res, err := client.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
panic(res.Status)
}
var body struct {
Results []Album `json:"results"`
}
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
panic(err)
}
if len(body.Results) == 0 {
fmt.Println("no soundtrack album known")
}
for _, a := range body.Results {
fmt.Printf("%s by %s (%d tracks)\n", a.Album, a.Artist, a.TrackCount)
for _, t := range a.Tracks {
fmt.Printf("%d. %s by %s\n", t.Number, t.Title, t.Artist)
}
}
}Parametri
movie_idpercorsoobbligatorioID numerico del film, per esempio155.api_keyqueryuno dei dueLa tua chiave. Usa questa o l'headerAuthorization: Bearer.
Campi della risposta
| Campo | Tipo | Note |
|---|---|---|
id | intero | ID del film. Assente quando usi append_to_response. |
results | array | Album. Vuoto quando non è noto alcun album. Oggi ne contiene al massimo uno. |
results[].source | stringa | Da dove viene l'album: musicbrainz o deezer. |
results[].album | stringa | Titolo dell'album. |
results[].artist | stringa o null | Artista dell'album, per esempio Hans Zimmer &. |
results[].released | stringa o null | Data di uscita come YYYY-MM-DD. |
results[].url | stringa o null | Link alla pagina dell'album presso la fonte. |
results[].track_count | intero | Numero di brani dell'album. |
results[].tracks | array | Brani nell'ordine dell'album. |
results[].tracks[].disc | intero | Numero del disco, a partire da 1. |
results[].tracks[].number | intero | Numero del brano sul disco. |
results[].tracks[].title | stringa | Titolo del brano. |
results[].tracks[].artist | stringa | Artista del brano. |
results[].tracks[].duration_ | intero | Durata in millisecondi. |
Leggi per nome le chiavi che usi e salta le altre.
Risposta di esempio
{
"id": 155,
"results": [
{
"source": "musicbrainz",
"album": "The Dark Knight",
"artist": "Hans Zimmer & James Newton Howard",
"released": "2008-07-15",
"url": "https://musicbrainz.org/release/814b2f7b-c27c-451e-abac-a316d2e6cea9",
"track_count": 14,
"tracks": [
{ "disc": 1, "number": 1, "title": "Why So Serious?", "artist": "Hans Zimmer", "duration_ms": 554000 },
{ "disc": 1, "number": 2, "title": "I'm Not a Hero", "artist": "Hans Zimmer", "duration_ms": 395000 },
{ "disc": 1, "number": 3, "title": "Harvey Two-Face", "artist": "James Newton Howard", "duration_ms": 377000 }
]
}
]
}L'elenco dei brani è tagliato a 3 su 14. Un titolo senza un album noto, come Fight Club (id 550), risponde con una lista vuota:
{
"id": 550,
"results": []
}Ottenere la colonna sonora di una serie
GET / restituisce la stessa struttura per una serie. Passa l'ID della serie, per esempio 1396. Breaking Bad non ha un album noto, quindi il suo array results è vuoto.
| Metodo e percorso | Restituisce | Parametri |
|---|---|---|
GET / | id e results | movie_id |
GET / | id e results | tv_id |
append_ | Lo stesso results sotto soundtracks | Aggiunto ai dettagli di un film o di una serie |
Per ottenere l'album mentre carichi la pagina di un film, aggiungilo ai dettagli:
curl -sf "https://api.amodb.dev/3/movie/155?append_to_response=credits,soundtracks" \
-H "Authorization: Bearer $AMODB_KEY"Il blocco aggiunto sta sotto la chiave soundtracks della scheda. Contiene results e non ha un id proprio. Conta come una sola richiesta.
Costruire una lista «musica in questo film»
Ordina per disc e number, mostra il titolo e l'artista, e nascondi il blocco quando results è vuoto. Le funzioni qui sotto restituiscono righe di testo semplice che puoi mettere in un elemento di lista.
function clock(ms) {
const s = Math.round(ms / 1000);
return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
}
function musicLines(results) {
const album = results[0];
if (!album) return [];
return [...album.tracks]
.sort((a, b) => a.disc - b.disc || a.number - b.number)
.map((t) => `${t.title} by ${t.artist} (${clock(t.duration_ms)})`);
}Alcune idee di interfaccia che non richiedono dati aggiuntivi:
| Idea | Come |
|---|---|
| Elenco numerato | Usare number come numero dell'elenco, e raggruppare per disc quando ci sono più dischi. |
| Link all'album | Collegare il nome dell'album a url quando non è null. |
| Durata totale | Sommare duration_ms su tutti i brani. |
| Abbinamento con i mood | Mostrare la lista accanto agli indicatori di mood dello stesso titolo. |
Errori
Ogni errore restituisce success a false con uno status_code numerico, come fa TMDB.
| HTTP | status_code | Quando |
|---|---|---|
| 401 | 7 | La chiave manca o è sbagliata. |
| 402 | 36 | Il periodo del piano è terminato. |
| 429 | 25 | Oltre le tue richieste al minuto. Attendi i secondi di Retry-After. |
L'endpoint delle colonne sonore non risponde 404 per un ID sconosciuto. Risponde 200 con un array results vuoto. Aggiunto ai dettagli, un ID sconosciuto dà un 404 dalla chiamata dei dettagli. Vedi errori per tutti i codici e limiti di richieste per gli header.
Note pratiche
- Come gli altri dati dei dettagli, le colonne sonore restano in cache sull'edge per 6 ore. Una cache client più breve non porta nulla.
- Usa
append_su una pagina di dettagli che già carichi. Risparmia una richiesta delle tue 20, 40 o 120 richieste al minuto.to_ response= soundtracks - Non pretendere che un album esista. Nascondi il blocco musicale quando
resultsè vuoto. - Alcuni album vengono da MusicBrainz e altri da Deezer. Il film 27205 (Inception) ha un album Deezer. La struttura è la stessa, quindi controlla
sourcesolo se la mostri. - I nomi di brani e artisti sono semplici stringhe e possono contenere qualsiasi carattere. Salvali in UTF-8 e fai l'escape quando li metti nell'HTML.
- Per il trailer dello stesso titolo, vedi video e trailer.