API לטריילרים של סרטים

קבלת הטריילר הרשמי של סרט

GET /3/movie/{movie_id}/videos מחזיר כל סרטון שמצורף לסרט. לכל פריט יש type, סימון official, קוד שפה, חותמת זמן published_at, וה-site וה-key שמזהים את הסרטון. השאירו את הפריטים שבהם type הוא Trailer ו-official הוא true, וקיבלתם את הטריילר.

מקבלים רשימת רשומות סרטונים שאפשר לדרג בעצמכם, לא זרם. התגובה נותנת שם לסרטון ואומרת איפה הוא נמצא, והעמוד שלכם בונה את הנגן מ-site ומ-key. אותו מבנה חוזר לסדרות. נתיבים של עונה ופרק עונים ברשימה ריקה.

אילו נתונים מקבלים

שדות בכל סרטון:

מתחילים בשלושה שלבים

1. בחרו מסלול בעמוד תמחור. כל מסלול מחזיר את כל הנתונים, ולכן בוחרים לפי בקשות לדקה.
2. צרו מפתח בלוח הבקרה של החשבון. הוא 32 תווים הקסדצימליים באותיות קטנות.
3. קראו ל-GET /3/movie/{movie_id}/videos עם המפתח ב-api_key או בכותרת Authorization: Bearer.

בקשה לדוגמה

הדוגמה מבקשת את הסרטונים של Inception (מזהה 27205), מדרגת אותם בקוד ומדפיסה את הטוב ביותר. הדירוג מציב קודם התאמות שפה, אחר כך Trailer לפני Teaser, אחר כך רשמי לפני לא רשמי, ואז את ה-published_at החדש ביותר.

curl -s "https://api.amodb.dev/3/movie/27205/videos" \
  -H "Authorization: Bearer $AMODB_KEY"

const BASE = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const TYPE_RANK = { Trailer: 0, Teaser: 2 };

function rank(video, lang) {
  const language = video.iso_639_1 === lang ? 0 : 10;
  const type = TYPE_RANK[video.type] ?? 4;
  return language + type + (video.official ? 0 : 1);
}

async function pickTrailer(movieId, lang = 'en') {
  const res = await fetch(`${BASE}/movie/${movieId}/videos`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  const { results } = await res.json();
  results.sort(
    (a, b) => rank(a, lang) - rank(b, lang) || (b.published_at || '').localeCompare(a.published_at || ''),
  );
  return results[0] ?? null;
}

const trailer = await pickTrailer(27205, 'en');
console.log(trailer ? `${trailer.name}: ${trailer.site} ${trailer.key}` : 'no video found');

תגובה מקוצרת: 2 הראשונים מתוך 42 סרטונים. הרשימה מכילה את כל השפות.

{
  "id": 27205,
  "results": [
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "The Dream Sequence",
      "key": "mpj9dL7swwk",
      "site": "YouTube",
      "size": 1080,
      "type": "Clip",
      "official": true,
      "published_at": "2022-03-09T01:00:20Z",
      "id": "mpj9dL7swwk"
    },
    {
      "iso_639_1": "en",
      "iso_3166_1": "US",
      "name": "35mm Theatrical Trailer #3",
      "key": "cdx31ak4KbQ",
      "site": "YouTube",
      "size": 1080,
      "type": "Trailer",
      "official": false,
      "published_at": "2022-03-07T06:00:19Z",
      "id": "cdx31ak4KbQ"
    }
  ]
}

בחירת הסרטון להפעלה

לכותר יש לעיתים קרובות כמה טריילרים רשמיים (הודעה ראשונה, גרסה סופית) לצד טיזרים וקטעים. דרגו אותם בסדר קבוע כדי שהעמוד לא יסיים עם סרטון טעויות צילום במקום הטריילר.

שוויון פותרים לפי published_at. מהחדש לישן נותן את הגרסה האחרונה, מהישן לחדש נותן את ההודעה הראשונה.

שפות של טריילרים

סרטונים מסומנים בשפה דרך iso_639_1, ולכותר אחד יכולים להיות טריילרים בכמה שפות. ל-Inception יש 42 סרטונים ב-9 שפות. amodb מחזיר את כולם בתגובה אחת. הפרמטרים language ו-include_video_language אינם משפיעים על נקודות הקצה של סרטונים, ולכן בחרו את השפה בקוד.

דרגו בתוך כל שלב לפי סוג וסימון official כמו בדוגמה. שפות הסרטונים נגזרות מההעלאה, לא מ-14 שפות הממשק שמפורטות בעמוד שפות, ולכן טריילר יכול להיות cs או he.

טריילרים לסדרות

טריילר של סדרה נמצא ב-/3/tv/1396/videos (Breaking Bad), שמכיל 9 טריילרים. פונקציית הדירוג למעלה עובדת כמו שהיא, כי השדות לא משתנים. נתיבי עונה ופרק כמו /3/tv/1396/season/1/videos עונים 200 עם רשימת results ריקה, ולכן קראו את רשימת הסדרה. את רשימת הנתיבים המלאה ראו בעמוד סרטונים וטריילרים.

בניית פס טריילרים

פס טריילרים של סרטים שמוצגים עכשיו דורש קריאת רשימה אחת וקריאה אחת לכל כותר. הקריאה GET /3/movie/now_playing (ראו טרנדים ורשימות) ועוד עשר קריאות סרטונים הן 11 בקשות לעשרה כותרים. שמרו את ה-key שנבחר ליד מזהה הסרט. טריילרים משתנים לעיתים רחוקות, ולכן רעננו בחירה שמורה כל כמה שעות או כשכותר יוצא מחדש.

איך זה בהשוואה

תמחור

המסלולים בתשלום מראש. קונים 1, 3, 6, 12 או 24 חודשים ומקבלים 0, 10, 20, 30 או 40 אחוז הנחה לתקופות הארוכות יותר. שום דבר לא מתחדש מעצמו. המסלולים של 20, 40 ו-120 בקשות לדקה מגישים כולם כל נקודת קצה בעמוד הזה, ולכן פס טריילרים עמוס הוא שאלה של קצב בלבד. אין מסלול חינמי ואין תקופת ניסיון. השוו מסלולים בעמוד תמחור.