# API סרטונים וטריילרים > נקודות הקצה של הסרטונים מפרטות את הטריילרים, הטיזרים, הקטעים והפיצ'רטים שמצורפים לסרט או לסדרה. כל פריט נותן שם מארח, מפתח וידאו, סוג, דגל רשמי, גודל ותאריך פרסום. קיימים נתיבי עונה ופרק אבל הם לא מחזירים סרטונים. סננו לפי שפה וסוג בקוד שלכם. ## נקודת קצה `GET /3/movie/{movie_id}/videos` ```bash curl "https://api.amodb.dev/3/movie/550/videos" \ -H "Authorization: Bearer $AMODB_KEY" ``` תגובה: ```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": "20th Anniversary Trailer", "key": "dfeUzm6KF4g", "site": "YouTube", "size": 1080, "type": "Trailer", "official": true, "published_at": "2019-10-15T18:59:47Z", "id": "dfeUzm6KF4g" } ] } ``` ## קבלת סרטונים של סרט `GET /3/movie/{movie_id}/videos` מחזיר את רשומות הסרטונים שמצורפות לסרט אחד. רשומה היא מטא-נתונים בלבד: שם, המארח שמגיש את הסרטון, מפתח הסרטון במארח הזה, סוג וכמה דגלים. amodb לא מחזיר קבצי וידאו. הדוגמה מדפיסה את הטריילר הרשמי הראשון באנגלית, ואם אין כזה, כל טריילר באנגלית. ```bash curl -s "https://api.amodb.dev/3/movie/550/videos" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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'); ``` ```python 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 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; ``` ```go 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. ```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`: סדר עולה נותן את הטריילר הראשון, סדר יורד נותן את האחרון. ```js 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 השפות המוגשות מפורטות בעמוד [שפות](https://amodb.dev/he/languages/). ## נקודות קצה נוספות לסרטונים הנתיבים שלמטה מחזירים את אותו מבנה של `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`. עמודי הסדרות והעונות מתוארים ב[סדרות טלוויזיה](https://amodb.dev/he/tv-series/) וב[עונות ופרקים](https://amodb.dev/he/tv-seasons-episodes/). ## שגיאות | HTTP | status_code | מתי | | ---- | ----------- | ------------------------------------------------------ | | 401 | 7 | המפתח חסר או שגוי. | | 402 | 36 | תקופת המסלול הסתיימה. | | 404 | 34 | אין עונה או פרק עם המזהה הזה, או מזהה שאינו מספר. | | 405 | 37 | השתמשתם בשיטת כתיבה בנתיב סרטונים. | | 429 | 25 | עברתם את הבקשות שלכם לדקה. המתינו `Retry-After` שניות. | מזהה סרט או סדרה שלא קיים אינו שגיאה כאן: נתיב הסרטונים עונה 200 עם `"results": []`, בדיוק כמו כותר מוכר בלי סרטונים. נתיב הפרטים עונה 404 למזהה לא מוכר. עוד על [שגיאות](https://amodb.dev/he/errors/) ו[מגבלות קצב](https://amodb.dev/he/rate-limits/). ## הערות מעשיות - שמרו את ה-`site` וה-`key` שנבחרו יחד עם הכותר, לא כתובת מלאה, כדי שתוכלו להחליף נגן בהמשך. - רשימות סרטונים עוקבות אחרי מטמון הפרטים של 6 שעות בקצה. מטמון לקוח של כמה שעות תואם אותו. - הערך `size` הוא 1080 בכל רשומה כיום, ולכן הוא לא יגיד לכם איזה קטע קל. תנו לנגן לבחור את האיכות. - אל תסתמכו על קיום טריילר אחד. הסתירו את כפתור ההפעלה כשפונקציית הבחירה שלכם מחזירה null. - לסדר של `results` אין משמעות. מיינו בקוד שלכם. - לקבצי פוסטרים ותמונות רקע ראו [תמונות](https://amodb.dev/he/images-api/). לתצוגת מקרי השימוש ראו [API טריילרים לסרטים](https://amodb.dev/he/movie-trailer-api/). ## שאלות ותשובות ### איך מקבלים רק את הטריילר הרשמי? סננו את מערך results לפי type השווה ל-Trailer ו-official השווה ל-true. אם נשארו כמה, מיינו לפי published_at כדי לקחת את המוקדם או את המאוחר ביותר. ### איך מקבלים סרטונים בשפה שלי? נקודת הקצה מחזירה כל סרטון של הכותר ומתעלמת מ-language ומ-include_video_language. סננו את results לפי iso_639_1 בקוד שלכם, למשל ru קודם ו-en כגיבוי. לכותרים רבים אין סרטון בשפה מסוימת. ### איך מנגנים סרטון מהתגובה? השתמשו בשדה site כדי לבחור נגן ובשדה key כמזהה הסרטון במארח הזה. בנתונים המוגשים כיום site הוא תמיד YouTube. בנו את כתובת ההטמעה או הצפייה לפי התבנית של המארח עצמו. amodb מחזיר מטא-נתונים, לא קבצי וידאו. ### האם לפרקים ולעונות יש סרטונים משלהם? לא. נתיבי הסרטונים של עונה ושל פרק עונים 200 עם מערך results ריק. רק לסרטים ולסדרות יש רשומות סרטון. ## עמודים קשורים - [API פרטי סרט](https://amodb.dev/he/movies/): API פרטי סרט עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סרט לפי מזהה, הוסיפו קרדיטים, דירוגים, מצבי רוח ופסקולים עם append_to_response, ב-14 שפות. - [API סדרות טלוויזיה](https://amodb.dev/he/tv-series/): API סדרות טלוויזיה עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סדרה לפי מזהה ב-GET /3/tv/{series_id} עם עונות, רשתות והפרק הבא, וגם סיווגי גיל וספקי צפייה. - [API עונות ופרקים של סדרות](https://amodb.dev/he/tv-seasons-episodes/): API עונות ופרקים של סדרות עם אותם נתיבים ו-JSON כמו TMDB v3. קראו עונה עם כל הפרקים שלה, או פרק אחד עם תאריך שידור, משך ותמונה מהפרק, עם crew ו-guest_stars. - [API לטריילרים של סרטים](https://amodb.dev/he/movie-trailer-api/): API לטריילרים של סרטים על נקודת הקצה GET /3/movie/{movie_id}/videos של TMDB v3. דרגו טריילרים, טיזרים וקטעים לפי סוג, סימון רשמי וקוד שפה, בבקשה אחת. - [API תמונות ושרת תמונות](https://amodb.dev/he/images-api/): API תמונות סרטים עם נתיבי TMDB v3: הציגו פוסטרים, תמונות רקע, לוגואים ותמונות סצנה לכל כותר, וטענו אותם מ-img.amodb.dev ב-10 גדלים בלי מפתח. - [מדריך למתחילים](https://amodb.dev/he/quickstart/): בצעו את הקריאה הראשונה ל-amodb: קבלו מפתח, בקשו פרטי סרט ב-curl, JavaScript, Python, PHP או Go, ואז טענו את הפוסטר מ-img.amodb.dev. פחות מ-2 דקות. עודכן: 2026-10-18. Source: https://amodb.dev/he/videos-trailers/