פסקולים
GET /3/movie/{movie_id}/soundtracks ו-GET /3/tv/{tv_id}/soundtracks מחזירים את אלבום הפסקול של כותר אחד ברשימת results. לכל אלבום יש מקור, שם, אמן, תאריך יציאה, קישור ורשימת tracks עם דיסק, מספר, שם, אמן ומשך. הוסיפו append_to_response=soundtracks כדי למזג אותו לפרטי הכותר. כך הפסקול מגיע יחד עם הפרטים בבקשה אחת.
קבלת הפסקול של סרט
GET / מחזיר את אלבום הפסקול של סרט אחד. התגובה נושאת את ה-id של הסרט ומערך results. כל פריט הוא אלבום עם הפרטים שלו ורשימת tracks.
הדוגמה טוענת את The Dark Knight (מזהה 155) ומדפיסה את האלבום ושורה אחת לכל רצועה.
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)
}
}
}פרמטרים
movie_idנתיבחובהמזהה סרט מספרי, למשל155.api_keyשאילתהאחד משנייםהמפתח שלכם. השתמשו בו או בכותרתAuthorization: Bearer.
שדות התגובה
| שדה | סוג | הערות |
|---|---|---|
id | integer | מזהה הסרט. לא קיים כשמשתמשים ב-append_to_response. |
results | array | אלבומים. ריק כשלא ידוע אלבום. כיום יש בו לכל היותר אחד. |
results[].source | string | מאיפה האלבום מגיע: musicbrainz או deezer. |
results[].album | string | כותרת האלבום. |
results[].artist | string או null | אמן האלבום, למשל Hans Zimmer &. |
results[].released | string או null | תאריך יציאה בצורה YYYY-MM-DD. |
results[].url | string או null | קישור לעמוד האלבום במקור. |
results[].track_count | integer | מספר הרצועות באלבום. |
results[].tracks | array | רצועות לפי סדר האלבום. |
results[].tracks[].disc | integer | מספר הדיסק, מתחיל ב-1. |
results[].tracks[].number | integer | מספר הרצועה בדיסק. |
results[].tracks[].title | string | כותרת הרצועה. |
results[].tracks[].artist | string | אמן הרצועה. |
results[].tracks[].duration_ | integer | האורך באלפיות שנייה. |
קראו את המפתחות שאתם משתמשים בהם לפי שם ודלגו על מפתחות אחרים.
תגובה לדוגמה
{
"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 }
]
}
]
}רשימת הרצועות קוצרה ל-3 מתוך 14. כותר בלי אלבום ידוע, כמו Fight Club (מזהה 550), מחזיר רשימה ריקה:
{
"id": 550,
"results": []
}קבלת הפסקול של סדרה
GET / מחזיר את אותו מבנה לסדרה. העבירו את מזהה הסדרה, למשל 1396. ל-Breaking Bad אין אלבום ידוע, ולכן מערך results שלה ריק.
| שיטה ונתיב | מה מוחזר | פרמטרים |
|---|---|---|
GET / | id ו-results | movie_id |
GET / | id ו-results | tv_id |
append_ | אותו results תחת soundtracks | נוסף לפרטי סרט או סדרה |
כדי לקבל את האלבום בזמן טעינת עמוד סרט, צרפו אותו לפרטים:
curl -sf "https://api.amodb.dev/3/movie/155?append_to_response=credits,soundtracks" \
-H "Authorization: Bearer $AMODB_KEY"הבלוק המצורף יושב תחת המפתח soundtracks ברשומה. הוא מחזיק results ואין לו id משלו. הוא נספר כבקשה אחת.
בניית רשימת המוזיקה בסרט
מיינו לפי disc ו-number, הציגו את הכותרת ואת האמן, והסתירו את הבלוק כש-results ריק. הפונקציות שלמטה מחזירות שורות טקסט פשוט שאפשר לשים באלמנט רשימה.
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)})`);
}כמה רעיונות לממשק שלא צריכים נתונים נוספים:
| רעיון | איך |
|---|---|
| רשימה ממוספרת | השתמשו ב-number כמספר הפריט ברשימה, וקבצו לפי disc כשיש כמה דיסקים. |
| קישור לאלבום | קשרו את שם האלבום ל-url כשהוא לא null. |
| אורך כולל | חברו את duration_ms של כל הרצועות. |
| שילוב עם מצב רוח | הציגו את הרשימה ליד מדדי מצב רוח של אותו כותר. |
שגיאות
כל כשל מחזיר success שהוא false ו-status_code מספרי, כמו ב-TMDB.
| HTTP | status_code | מתי |
|---|---|---|
| 401 | 7 | המפתח חסר או שגוי. |
| 402 | 36 | תקופת המסלול הסתיימה. |
| 429 | 25 | מעל הבקשות שלכם לדקה. המתינו Retry-After שניות. |
נקודת הקצה של הפסקולים לא עונה 404 למזהה לא מוכר. היא עונה 200 עם מערך results ריק. כשמצרפים לפרטים, מזהה לא מוכר הוא 404 מקריאת הפרטים. כל הקודים בעמוד שגיאות, והכותרות בעמוד מגבלות קצב.
הערות מעשיות
- כמו נתוני פרטים אחרים, פסקולים נשמרים בקצה במטמון 6 שעות. מטמון קצר יותר בצד הלקוח לא מועיל.
- השתמשו ב-
append_בעמוד פרטים שאתם כבר טוענים. זה חוסך בקשה אחת מתוך 20, 40 או 120 הבקשות שלכם לדקה.to_ response= soundtracks - אל תדרשו שאלבום יהיה קיים. הסתירו את בלוק המוזיקה כש-
resultsריק. - חלק מהאלבומים מגיעים מ-MusicBrainz ואחרים מ-Deezer. לסרט 27205 (Inception) יש אלבום ב-Deezer. המבנה זהה, ולכן בדקו את
sourceרק אם אתם מציגים אותו. - שמות רצועות ואמנים הם מחרוזות רגילות ויכולים להכיל כל תו. שמרו אותם כ-UTF-8 ובצעו להם escape כשאתם מציבים אותם ב-HTML.
- לטריילר של אותו כותר ראו סרטונים וטריילרים.