API סרטונים וטריילרים

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

עודכן צפייה כ-Markdown

קבלת סרטונים של סרט

GET /3/movie/{movie_id}/videos מחזיר את רשומות הסרטונים שמצורפות לסרט אחד. רשומה היא מטא-נתונים בלבד: שם, המארח שמגיש את הסרטון, מפתח הסרטון במארח הזה, סוג וכמה דגלים. amodb לא מחזיר קבצי וידאו.

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

bashjspyphpgo
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 בקוד שלכם.

שדות התגובה

שדהסוגהערות
idintegerמזהה הסרט.
resultsarrayרשומות סרטונים, לא ממוינות לפי סוג או תאריך. ריק כשלא ידוע אף סרטון.
results[].iso_639_1, results[].iso_3166_1stringהשפה והמדינה של הסרטון, למשל en ו-US.
results[].namestringכותרת הסרטון, למשל #TBT Trailer.
results[].keystringמזהה הסרטון במארח הזה.
results[].sitestringשם מארח הווידאו. כיום תמיד YouTube.
results[].sizeintegerרזולוציה אנכית. כיום תמיד 1080.
results[].typestringTrailer, Teaser, Clip, Featurette, Behind the Scenes, Bloopers, Opening Credits או Recap.
results[].officialbooleantrue כשהאולפן או בעל הזכויות פרסם אותו.
results[].published_atstringחותמת זמן בפורמט ISO 8601, עם אלפיות שנייה או בלעדיהן.
results[].idstringמזהה רשומת הסרטון. שווה ל-key.

תגובה לדוגמה

מוצגות שלוש מתוך 19 הרשומות של סרט 550.

JSON
{
  "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: סדר עולה נותן את הטריילר הראשון, סדר יורד נותן את האחרון.

JavaScript
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 /tv/{series_id}/videosסרטונים של סדרה.
GET /tv/{series_id}/season/{season_number}/videosתמיד מערך results ריק.
GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/videosתמיד מערך results ריק.

אפשר גם להוסיף append_to_response=videos לקריאת פרטים של סרט או סדרה. הבלוק המצורף מחזיק results ואין בו id. עמודי הסדרות והעונות מתוארים בסדרות טלוויזיה ובעונות ופרקים.

שגיאות

HTTPstatus_codeמתי
4017המפתח חסר או שגוי.
40236תקופת המסלול הסתיימה.
40434אין עונה או פרק עם המזהה הזה, או מזהה שאינו מספר.
40537השתמשתם בשיטת כתיבה בנתיב סרטונים.
42925עברתם את הבקשות שלכם לדקה. המתינו Retry-After שניות.

מזהה סרט או סדרה שלא קיים אינו שגיאה כאן: נתיב הסרטונים עונה 200 עם "results": [], בדיוק כמו כותר מוכר בלי סרטונים. נתיב הפרטים עונה 404 למזהה לא מוכר. עוד על שגיאות ומגבלות קצב.

הערות מעשיות

  • שמרו את ה-site וה-key שנבחרו יחד עם הכותר, לא כתובת מלאה, כדי שתוכלו להחליף נגן בהמשך.
  • רשימות סרטונים עוקבות אחרי מטמון הפרטים של 6 שעות בקצה. מטמון לקוח של כמה שעות תואם אותו.
  • הערך size הוא 1080 בכל רשומה כיום, ולכן הוא לא יגיד לכם איזה קטע קל. תנו לנגן לבחור את האיכות.
  • אל תסתמכו על קיום טריילר אחד. הסתירו את כפתור ההפעלה כשפונקציית הבחירה שלכם מחזירה null.
  • לסדר של results אין משמעות. מיינו בקוד שלכם.
  • לקבצי פוסטרים ותמונות רקע ראו תמונות. לתצוגת מקרי השימוש ראו API טריילרים לסרטים.