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

> ה-API לטריילרים של סרטים הוא GET /3/movie/{movie_id}/videos ב-api.amodb.dev. לכל סרטון יש סוג, סימון רשמי, שפה ותאריך פרסום, כך שאפשר לבחור את הטריילר הרשמי במעבר אחד על הרשימה. סדרות מחזירות אותו מבנה. הנתיבים וה-JSON זהים ל-TMDB v3. התגובה היא רשימת רשומות ולא זרם וידאו, והנגן נבנה אצלכם.

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

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

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

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

| נקודת קצה                                                                  | מה מוחזר                                                              |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `GET /3/movie/{movie_id}/videos`                                           | טריילרים, טיזרים, קטעים, פיצ'רטים, מאחורי הקלעים וטעויות צילום של סרט |
| `GET /3/tv/{tv_id}/videos`                                                 | אותה רשימה לסדרה                                                      |
| `GET /3/tv/{tv_id}/season/{season_number}/videos`                          | תמיד רשימת `results` ריקה                                             |
| `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos` | תמיד רשימת `results` ריקה                                             |
| `GET /3/movie/{movie_id}` עם `append_to_response=videos`                   | פרטים וסרטונים בבקשה אחת                                              |

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

| שדה                       | סוג     | שימוש                                                                                                        |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `type`                    | string  | סוג הסרטון: `Trailer`, `Teaser`, `Clip`, `Featurette`, `Behind the Scenes` או `Bloopers`, כמו בעמוד הסרטונים |
| `official`                | boolean | `true` כשהסרטון מסומן כרשמי                                                                                  |
| `iso_639_1`, `iso_3166_1` | string  | קודי שפה ומדינה של הסרטון                                                                                    |
| `key`, `site`             | string  | מזהה הסרטון ושם האתר שמארח אותו, `YouTube` בכל סרטון שנראה                                                   |
| `size`                    | integer | רזולוציה אנכית, `1080` בכל סרטון שנראה                                                                       |
| `published_at`            | string  | חותמת זמן ISO 8601, מתאימה למיון מהחדש לישן                                                                  |
| `name`, `id`              | string  | כותרת הסרטון והמזהה שלו, שהוא אותה מחרוזת כמו `key`                                                          |

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

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

## בקשה לדוגמה

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

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

```js
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 סרטונים. הרשימה מכילה את כל השפות.

```json
{
  "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"
    }
  ]
}
```

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

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

| עדיפות | סינון                           | שימוש אופייני                           |
| ------ | ------------------------------- | --------------------------------------- |
| 1      | `Trailer`, רשמי, השפה מתאימה    | הסרטון להפעלה                           |
| 2      | `Trailer`, לא רשמי              | העלאות אזוריות או של מעריצים כשאין רשמי |
| 3      | `Teaser`, רשמי                  | קטעים קצרים לפני היציאה                 |
| 4      | `Clip`, `Featurette`            | גיבוי כדי שהמקום לא יישאר ריק           |
| לדלג   | `Behind the Scenes`, `Bloopers` | להציג ברשימת בונוסים נפרדת              |

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

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

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

| שלב | מה לעשות                                                     |
| --- | ------------------------------------------------------------ |
| 1   | השאירו את הסרטונים ש-`iso_639_1` שלהם תואם למשתמש, למשל `ru` |
| 2   | אם אין התאמה, השאירו `en`                                    |
| 3   | אם עדיין אין התאמה, השאירו את השאר                           |

דרגו בתוך כל שלב לפי סוג וסימון `official` כמו בדוגמה. שפות הסרטונים נגזרות מההעלאה, לא מ-14 שפות הממשק שמפורטות בעמוד [שפות](https://amodb.dev/he/languages/), ולכן טריילר יכול להיות `cs` או `he`.

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

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

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

פס טריילרים של סרטים שמוצגים עכשיו דורש קריאת רשימה אחת וקריאה אחת לכל כותר. הקריאה `GET /3/movie/now_playing` (ראו [טרנדים ורשימות](https://amodb.dev/he/trending-lists/)) ועוד עשר קריאות סרטונים הן 11 בקשות לעשרה כותרים. שמרו את ה-`key` שנבחר ליד מזהה הסרט. טריילרים משתנים לעיתים רחוקות, ולכן רעננו בחירה שמורה כל כמה שעות או כשכותר יוצא מחדש.

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

| יכולת               | גירוד דפים בעצמכם   | API למטא-נתונים עם מסלול חינמי | amodb                                                      |
| ------------------- | ------------------- | ------------------------------ | ---------------------------------------------------------- |
| סימון רשמי          | ניחוש מכותרת הדף    | ראו במסמכים שלהם               | ערך בוליאני `official` בכל סרטון                           |
| סינון לפי סוג סרטון | ניתוח טקסט          | ראו במסמכים שלהם               | שישה ערכי `type`                                           |
| בחירת שפה           | אזור שפה אחד לכל דף | ראו במסמכים שלהם               | `iso_639_1` ו-`iso_3166_1` בכל סרטון, מסננים בקוד שלכם     |
| סדרות ופרקים        | דפים נפרדים לסריקה  | ראו במסמכים שלהם               | סדרות משתמשות באותה נקודת קצה, רשימות עונה ופרק ריקות      |
| תחזוקה              | נשבר כשהמבנה משתנה  | תלוי בספק                      | מבנה JSON יציב אחד                                         |
| תנאים               | הסיכון עליכם        | ראו את התנאים שלהם             | מסלולים בתשלום, ראו [תמחור](https://amodb.dev/he/pricing/) |

## תמחור

המסלולים בתשלום מראש. קונים 1, 3, 6, 12 או 24 חודשים ומקבלים 0, 10, 20, 30 או 40 אחוז הנחה לתקופות הארוכות יותר. שום דבר לא מתחדש מעצמו. המסלולים של 20, 40 ו-120 בקשות לדקה מגישים כולם כל נקודת קצה בעמוד הזה, ולכן פס טריילרים עמוס הוא שאלה של קצב בלבד. אין מסלול חינמי ואין תקופת ניסיון. השוו מסלולים בעמוד [תמחור](https://amodb.dev/he/pricing/).

## שאלות ותשובות

### איך מקבלים את הטריילר הרשמי של סרט?

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

### האם ה-API מחזיר קובץ וידאו או זרם?

לא. הוא מחזיר מטא-נתונים של כל סרטון: name, type, site, key, size, language ותאריכים. את קישור הנגן בונים מ-site ו-key, או מטמיעים את הסרטון בעמוד שלכם. פוסטרים ותמונות סצנה מגיעים מ-img.amodb.dev.

### איך מקבלים טריילרים בשפה שלי?

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

### אפשר לקבל טריילרים לסדרות ולפרקים?

לסדרות, כן: השתמשו ב-/3/tv/{tv_id}/videos. השדות זהים, ולכן קוד הדירוג שכתבתם לסרטים עובד בלי שינוי. נתיבי סרטונים של עונה ופרק מחזירים מערך results ריק, ולכן השתמשו ברשימת הסדרה.

### כמה בקשות צורכת שליפת טריילר?

בקשה אחת לכל כותר. עם append_to_response=videos הטריילר מגיע בתוך קריאת הפרטים, ולכן פרטים ועוד טריילר הם עדיין בקשה אחת מתוך 20, 40 או 120 הבקשות שלכם לדקה.

## עמודים קשורים

- [API סרטונים וטריילרים](https://amodb.dev/he/videos-trailers/): API סרטונים עם נתיבי TMDB v3, כמו GET /3/movie/{movie_id}/videos: רשימת טריילרים, טיזרים, קטעים ופיצ'רטים של סרט או סדרה, ואז סינון לפי סוג ושפה בקוד שלכם.
- [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} עם עונות, רשתות והפרק הבא, וגם סיווגי גיל וספקי צפייה.
- [נקודות קצה של מגמות ורשימות](https://amodb.dev/he/trending-lists/): API סרטים פופולריים עם נתיבי TMDB v3: טבלאות יומיות ושבועיות, ורשימות מוקרנים עכשיו, פופולריים, מדורגים וצפויים לסרטים ולסדרות, במטמון 30 דקות.
- [שפות](https://amodb.dev/he/languages/): amodb מגיש כותרים, תקצירים ושמות ב-14 שפות. העבירו בפרמטר language תגית בסגנון TMDB כמו ru-RU או pt-BR; כל תגית אחרת חוזרת לאנגלית, בלי שגיאה.
- [מדריך למתחילים](https://amodb.dev/he/quickstart/): בצעו את הקריאה הראשונה ל-amodb: קבלו מפתח, בקשו פרטי סרט ב-curl, JavaScript, Python, PHP או Go, ואז טענו את הפוסטר מ-img.amodb.dev. פחות מ-2 דקות.

עודכן: 2026-10-18. Source: https://amodb.dev/he/movie-trailer-api/