API סרטונים וטריילרים
נקודות הקצה של הסרטונים מפרטות את הטריילרים, הטיזרים, הקטעים והפיצ'רטים שמצורפים לסרט או לסדרה. כל פריט נותן שם מארח, מפתח וידאו, סוג, דגל רשמי, גודל ותאריך פרסום. קיימים נתיבי עונה ופרק אבל הם לא מחזירים סרטונים. סננו לפי שפה וסוג בקוד שלכם.
קבלת סרטונים של סרט
GET / מחזיר את רשומות הסרטונים שמצורפות לסרט אחד. רשומה היא מטא-נתונים בלבד: שם, המארח שמגיש את הסרטון, מפתח הסרטון במארח הזה, סוג וכמה דגלים. amodb לא מחזיר קבצי וידאו.
הדוגמה מדפיסה את הטריילר הרשמי הראשון באנגלית, ואם אין כזה, כל טריילר באנגלית.
curl -s "https://api.amodb.dev/3/movie/550/videos" \
-H "Authorization: Bearer $AMODB_KEY"const url = 'https://api.amodb.dev/3/movie/550/videos';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results } = await res.json();
const trailers = results.filter((v) => v.type === 'Trailer' && v.iso_639_1 === 'en');
const pick = trailers.find((v) => v.official) ?? trailers[0];
console.log(pick ? `${pick.name} (${pick.site}, key ${pick.key})` : 'no trailer');import os
import requests
r = requests.get(
"https://api.amodb.dev/3/movie/550/videos",
headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
timeout=10,
)
r.raise_for_status()
trailers = [v for v in r.json()["results"] if v["type"] == "Trailer" and v["iso_639_1"] == "en"]
official = [v for v in trailers if v["official"]]
pick = (official or trailers or [None])[0]
print(f"{pick['name']} ({pick['site']}, key {pick['key']})" if pick else "no trailer")<?php
$url = 'https://api.amodb.dev/3/movie/550/videos';
$ch = curl_init($url);
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");
}
$trailers = array_values(array_filter(
json_decode($body, true)['results'],
fn($v) => $v['type'] === 'Trailer' && $v['iso_639_1'] === 'en'
));
$official = array_values(array_filter($trailers, fn($v) => $v['official']));
$pick = $official[0] ?? $trailers[0] ?? null;
echo $pick ? "{$pick['name']} ({$pick['site']}, key {$pick['key']})" : 'no trailer', PHP_EOL;package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
type Videos struct {
Results []struct {
Name string `json:"name"`
Key string `json:"key"`
Site string `json:"site"`
Type string `json:"type"`
Language string `json:"iso_639_1"`
Official bool `json:"official"`
} `json:"results"`
}
func main() {
url := "https://api.amodb.dev/3/movie/550/videos"
req, _ := http.NewRequest("GET", url, 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 v Videos
if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
panic(err)
}
for _, r := range v.Results {
if r.Type == "Trailer" && r.Language == "en" && r.Official {
fmt.Printf("%s (%s, key %s)\n", r.Name, r.Site, r.Key)
return
}
}
fmt.Println("no official trailer")
}פרמטרים
movie_idנתיבחובהמזהה סרט מספרי, למשל550.api_keyשאילתהאחד משנייםהמפתח שלכם. השתמשו בו או בכותרתAuthorization: Bearer.language,include_video_languageשאילתהמתקבלים ומתעלמים מהם. התגובה תמיד מחזיקה כל סרטון של הכותר. סננו לפיiso_639_1בקוד שלכם.
שדות התגובה
| שדה | סוג | הערות |
|---|---|---|
id | integer | מזהה הסרט. |
results | array | רשומות סרטונים, לא ממוינות לפי סוג או תאריך. ריק כשלא ידוע אף סרטון. |
results[].iso_639_1, results[].iso_3166_1 | string | השפה והמדינה של הסרטון, למשל en ו-US. |
results[].name | string | כותרת הסרטון, למשל #TBT Trailer. |
results[].key | string | מזהה הסרטון במארח הזה. |
results[].site | string | שם מארח הווידאו. כיום תמיד YouTube. |
results[].size | integer | רזולוציה אנכית. כיום תמיד 1080. |
results[].type | string | Trailer, Teaser, Clip, Featurette, Behind the Scenes, Bloopers, Opening Credits או Recap. |
results[].official | boolean | true כשהאולפן או בעל הזכויות פרסם אותו. |
results[].published_at | string | חותמת זמן בפורמט ISO 8601, עם אלפיות שנייה או בלעדיהן. |
results[].id | string | מזהה רשומת הסרטון. שווה ל-key. |
תגובה לדוגמה
מוצגות שלוש מתוך 19 הרשומות של סרט 550.
{
"id": 550,
"results": [
{
"iso_639_1": "en",
"iso_3166_1": "US",
"name": "Theatrical Trailer (HD Fan Remaster)",
"key": "6JnN1DmbqoU",
"site": "YouTube",
"size": 1080,
"type": "Trailer",
"official": false,
"published_at": "2015-02-26T03:19:25Z",
"id": "6JnN1DmbqoU"
},
{
"iso_639_1": "en",
"iso_3166_1": "US",
"name": "#TBT Trailer",
"key": "BdJKm16Co6M",
"site": "YouTube",
"size": 1080,
"type": "Trailer",
"official": true,
"published_at": "2014-10-02T19:20:22Z",
"id": "BdJKm16Co6M"
},
{
"iso_639_1": "en",
"iso_3166_1": "US",
"name": "Mark Kermode introduces Fight Club | Film4 Interview",
"key": "tiWCNtGDGEY",
"site": "YouTube",
"size": 1080,
"type": "Featurette",
"official": true,
"published_at": "2015-05-08T15:59:05Z",
"id": "tiWCNtGDGEY"
}
]
}סוגי סרטונים
השדה type אומר מה הסרטון. התאימו אותו בדיוק, עם האותיות הגדולות שמוצגות.
| סוג | שימוש |
|---|---|
Trailer | הקידום הראשי. הציגו אותו בעמוד פרטים. |
Teaser | הודעה קצרה שקודמת לטריילר. |
Clip | סצנה שנלקחה מהסרט או מהפרק המוגמר. |
Featurette | קטע קצר על איך הכותר נוצר. |
Behind the Scenes | צילומים מהסט וראיונות. |
Bloopers | קטעים שנחתכו וליקוטי הצחות. |
Opening Credits | רצף הפתיחה של סדרה. |
Recap | סיכום של פרקים קודמים. |
ערכים אחרים יכולים להופיע עם הזמן, ולכן התייחסו ל-type לא מוכר כאל תוספת כללית ואל תיכשלו בגללו.
בחירת הסרטון הנכון
השתמשו באותו סדר לכל כותר. נסו את השפות שלכם לפי הסדר. בתוך שפה אחת, טריילרים רשמיים קודמים, אחריהם כל טריילר, ואז טיזרים, ואז קטעים. בתוך קבוצה מיינו לפי published_at: סדר עולה נותן את הטריילר הראשון, סדר יורד נותן את האחרון.
function pickVideo(results, langs = ['en']) {
const order = ['Trailer', 'Teaser', 'Clip'];
for (const lang of langs) {
for (const type of order) {
const group = results
.filter((v) => v.iso_639_1 === lang && v.type === type)
.sort((a, b) => Number(b.official) - Number(a.official) || Date.parse(a.published_at) - Date.parse(b.published_at));
if (group.length > 0) return group[0];
}
}
return null;
}
// Russian first, English as the fallback.
// const video = pickVideo(results, ['ru', 'en']);שפות
הפרמטרים language ו-include_video_language לא משנים את התגובה, ולכן קריאה אחת נותנת לכם כל סרטון של הכותר. כל רשומה נושאת iso_639_1 ו-iso_3166_1. לסרט 550 יש סרטונים שתויגו fr, en, es, pt, it, cs, pl ו-ru. סננו לפי iso_639_1 בקוד שלכם כפי שמוצג למעלה, ואז הראו למשתמש באיזו שפה הוא עומד לשמוע. לכותר יכול לא להיות סרטון בשפה שאתם רוצים, ולכן שמרו גיבוי באנגלית או בכל שפה. 14 השפות המוגשות מפורטות בעמוד שפות.
נקודות קצה נוספות לסרטונים
הנתיבים שלמטה מחזירים את אותו מבנה של id ו-results.
| שיטה ונתיב | מה מוחזר |
|---|---|
GET / | סרטונים של סדרה. |
GET / | תמיד מערך results ריק. |
GET / | תמיד מערך results ריק. |
אפשר גם להוסיף append_ לקריאת פרטים של סרט או סדרה. הבלוק המצורף מחזיק results ואין בו id. עמודי הסדרות והעונות מתוארים בסדרות טלוויזיה ובעונות ופרקים.
שגיאות
| HTTP | status_code | מתי |
|---|---|---|
| 401 | 7 | המפתח חסר או שגוי. |
| 402 | 36 | תקופת המסלול הסתיימה. |
| 404 | 34 | אין עונה או פרק עם המזהה הזה, או מזהה שאינו מספר. |
| 405 | 37 | השתמשתם בשיטת כתיבה בנתיב סרטונים. |
| 429 | 25 | עברתם את הבקשות שלכם לדקה. המתינו Retry-After שניות. |
מזהה סרט או סדרה שלא קיים אינו שגיאה כאן: נתיב הסרטונים עונה 200 עם "results": [], בדיוק כמו כותר מוכר בלי סרטונים. נתיב הפרטים עונה 404 למזהה לא מוכר. עוד על שגיאות ומגבלות קצב.
הערות מעשיות
- שמרו את ה-
siteוה-keyשנבחרו יחד עם הכותר, לא כתובת מלאה, כדי שתוכלו להחליף נגן בהמשך. - רשימות סרטונים עוקבות אחרי מטמון הפרטים של 6 שעות בקצה. מטמון לקוח של כמה שעות תואם אותו.
- הערך
sizeהוא 1080 בכל רשומה כיום, ולכן הוא לא יגיד לכם איזה קטע קל. תנו לנגן לבחור את האיכות. - אל תסתמכו על קיום טריילר אחד. הסתירו את כפתור ההפעלה כשפונקציית הבחירה שלכם מחזירה null.
- לסדר של
resultsאין משמעות. מיינו בקוד שלכם. - לקבצי פוסטרים ותמונות רקע ראו תמונות. לתצוגת מקרי השימוש ראו API טריילרים לסרטים.