Bandes originales
GET /3/movie/{movie_id}/soundtracks et GET /3/tv/{tv_id}/soundtracks renvoient l'album de la bande originale d'un titre dans une liste results. Chaque album a une source, un nom, un artiste, une date de sortie, un lien et une liste tracks avec disque, numéro, titre, artiste et durée. Ajoutez append_to_response=soundtracks pour la fusionner aux détails.
Obtenir la bande originale d'un film
GET / renvoie l'album de la bande originale d'un film. La réponse contient l'id du film et un tableau results. Chaque entrée est un album avec ses détails et une liste tracks.
L'exemple charge The Dark Knight (id 155) et affiche l'album et une ligne par morceau.
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)
}
}
}Paramètres
movie_idcheminobligatoireIdentifiant numérique du film, par exemple155.api_keyrequêtel'un des deuxVotre clé. Utilisez-la ou l'en-têteAuthorization: Bearer.
Champs de la réponse
| Champ | Type | Remarques |
|---|---|---|
id | entier | Identifiant du film. Absent quand vous utilisez append_to_response. |
results | tableau | Albums. Vide quand aucun album n'est connu. Aujourd'hui il en contient au plus un. |
results[].source | chaîne | D'où vient l'album : musicbrainz ou deezer. |
results[].album | chaîne | Titre de l'album. |
results[].artist | chaîne ou null | Artiste de l'album, par exemple Hans Zimmer &. |
results[].released | chaîne ou null | Date de sortie sous la forme YYYY-MM-DD. |
results[].url | chaîne ou null | Lien vers la page de l'album chez la source. |
results[].track_count | entier | Nombre de morceaux de l'album. |
results[].tracks | tableau | Morceaux dans l'ordre de l'album. |
results[].tracks[].disc | entier | Numéro du disque, à partir de 1. |
results[].tracks[].number | entier | Numéro du morceau sur le disque. |
results[].tracks[].title | chaîne | Titre du morceau. |
results[].tracks[].artist | chaîne | Artiste du morceau. |
results[].tracks[].duration_ | entier | Durée en millisecondes. |
Lisez par leur nom les clés que vous utilisez et ignorez les autres.
Exemple de réponse
{
"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 }
]
}
]
}La liste de morceaux est réduite à 3 sur 14. Un titre sans album connu, comme Fight Club (id 550), répond par une liste vide :
{
"id": 550,
"results": []
}Obtenir la bande originale d'une série
GET / renvoie la même forme pour une série. Passez l'identifiant de la série, par exemple 1396. Breaking Bad n'a aucun album connu : son tableau results est donc vide.
| Méthode et chemin | Renvoie | Paramètres |
|---|---|---|
GET / | id et results | movie_id |
GET / | id et results | tv_id |
append_ | Le même results sous soundtracks | Ajouté aux détails d'un film ou d'une série |
Pour obtenir l'album pendant le chargement d'une page de film, ajoutez-le aux détails :
curl -sf "https://api.amodb.dev/3/movie/155?append_to_response=credits,soundtracks" \
-H "Authorization: Bearer $AMODB_KEY"Le bloc ajouté se trouve sous la clé soundtracks de la fiche. Il contient results et n'a pas d'id propre. Il compte pour une seule requête.
Construire une liste « musique du film »
Triez par disc et number, affichez le titre et l'artiste, et masquez le bloc quand results est vide. Les fonctions ci-dessous renvoient des lignes de texte simple que vous pouvez placer dans un élément de liste.
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)})`);
}Quelques idées d'interface qui n'exigent aucune donnée supplémentaire :
| Idée | Comment |
|---|---|
| Liste numérotée | Utiliser number comme numéro de liste, et regrouper par disc quand il y a plusieurs disques. |
| Lien vers l'album | Relier le nom de l'album à url quand il n'est pas null. |
| Durée totale | Additionner duration_ms sur les morceaux. |
| Association avec les ambiances | Afficher la liste à côté des jauges d'ambiance du même titre. |
Erreurs
Chaque échec renvoie success à false avec un status_code numérique, comme le fait TMDB.
| HTTP | status_code | Quand |
|---|---|---|
| 401 | 7 | La clé est absente ou fausse. |
| 402 | 36 | La période de l'offre est terminée. |
| 429 | 25 | Au-dessus de vos requêtes par minute. Attendez les secondes de Retry-After. |
Le point de terminaison des bandes originales ne répond pas 404 pour un identifiant inconnu. Il répond 200 avec un tableau results vide. Ajouté aux détails, un identifiant inconnu donne un 404 de l'appel de détails. Voir erreurs pour tous les codes et limites de débit pour les en-têtes.
Remarques pratiques
- Comme les autres données de détails, les bandes originales sont mises en cache 6 heures en périphérie. Un cache client plus court n'apporte rien.
- Utilisez
append_sur une page de détails que vous chargez déjà. Cela économise une requête de vos 20, 40 ou 120 requêtes par minute.to_ response= soundtracks - N'exigez pas qu'un album existe. Masquez le bloc musique quand
resultsest vide. - Certains albums viennent de MusicBrainz et d'autres de Deezer. Le film 27205 (Inception) a un album Deezer. La forme est la même : ne vérifiez donc
sourceque si vous l'affichez. - Les noms de morceaux et d'artistes sont de simples chaînes et peuvent contenir n'importe quel caractère. Stockez-les en UTF-8 et échappez-les quand vous les placez dans du HTML.
- Pour la bande-annonce du même titre, voir vidéos et bandes-annonces.