# API מטא-נתונים רב-לשוני לסרטים

> ה-API הרב-לשוני הזה מגיש כותרות, תקצירים, סלוגנים, שמות ז'אנרים וביוגרפיות ב-14 שפות עם מפתח אחד: אנגלית, רוסית, אוקראינית, בלארוסית, סינית, פורטוגזית, בולגרית, עברית, צ'כית, רומנית, צרפתית, פולנית, איטלקית וספרדית. העבירו תגית של TMDB כמו ru-RU בפרמטר language. כשחסר תרגום, חזרו לאנגלית, והציגו עברית מימין לשמאל.

## קבלת נתוני סרטים ב-14 שפות

`GET /3/movie/{movie_id}?language=ru-RU` מחזיר את הכותרת, התקציר, הסלוגן ושמות הז'אנרים ברוסית. הפרמטר `language` מקבל תגיות של TMDB כמו `ru-RU` או `pt-BR` ופועל בכל נקודת קצה שמחזירה טקסט. המזהים נשארים זהים בכל שפה, ולכן שורה אחת במסד הנתונים שלכם משרתת את כולן.

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

## 14 השפות המוגשות

| שפה       | קוד  | תגית לדוגמה |
| --------- | ---- | ----------- |
| אנגלית    | `en` | `en-US`     |
| רוסית     | `ru` | `ru-RU`     |
| אוקראינית | `uk` | `uk-UA`     |
| בלארוסית  | `be` | `be-BY`     |
| סינית     | `zh` | `zh-CN`     |
| פורטוגזית | `pt` | `pt-BR`     |
| בולגרית   | `bg` | `bg-BG`     |
| עברית     | `he` | `he-IL`     |
| צ'כית     | `cs` | `cs-CZ`     |
| רומנית    | `ro` | `ro-RO`     |
| צרפתית    | `fr` | `fr-FR`     |
| פולנית    | `pl` | `pl-PL`     |
| איטלקית   | `it` | `it-IT`     |
| ספרדית    | `es` | `es-ES`     |

כל תגית אחרת חוזרת ל-`en`. יפנית וקוריאנית אינן מוגשות כשפות ממשק. הכותרות המקוריות שלהן עדיין חוזרות ב-`original_title` לסרטים וב-`original_name` לסדרות.

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

| נקודת קצה                                  | תוכן מתורגם                                                  |
| ------------------------------------------ | ------------------------------------------------------------ |
| `GET /3/movie/{movie_id}`                  | `title`, `overview`, `tagline`, שמות ז'אנרים                 |
| `GET /3/tv/{tv_id}`                        | `name`, `overview`, `tagline`, שמות ז'אנרים                  |
| `GET /3/tv/{tv_id}/season/{season_number}` | `name` ו-`overview` של עונה ופרק                             |
| `GET /3/person/{person_id}`                | `biography`                                                  |
| `GET /3/genre/movie/list`                  | שמות ז'אנרים למסננים ולתפריטים                               |
| `GET /3/movie/{movie_id}/translations`     | כל השפות של כותר בתגובה אחת                                  |
| `GET /3/movie/{movie_id}/images`           | פוסטרים מסומנים לפי שפה, מסוננים עם `include_image_language` |
| `GET /3/movie/{movie_id}/videos`           | סרטונים מסומנים לפי `iso_639_1`, כל השפות בתגובה אחת         |

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

1. בחרו מסלול בעמוד [תמחור](https://amodb.dev/he/pricing/). מספר השפות לא משתנה לפי המסלול, רק קצב הבקשות.
2. צרו מפתח בלוח הבקרה של החשבון.
3. קראו לכל נקודת קצה עם תגית `language`, ושלחו את המפתח כ-`api_key` או ככותרת Bearer.

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

דוגמת ה-bash מדפיסה את הכותרת של Fight Club (מזהה `550`) בשלוש שפות. היא משתמשת ב-`jq` כדי להדפיס שדה אחד. דוגמת ה-PHP מבקשת בלארוסית וחוזרת לאנגלית כשהתקציר ריק.

```bash
for lang in en-US ru-RU he-IL; do
  curl -s "https://api.amodb.dev/3/movie/550?language=$lang" \
    -H "Authorization: Bearer $AMODB_KEY" | jq -r '.title'
done
```

```php
<?php
function amodb(string $path, array $query = []): array
{
    $url = 'https://api.amodb.dev/3' . $path . '?' . http_build_query($query);
    $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");
    }
    return json_decode($body, true);
}

function localizedMovie(int $id, string $lang): array
{
    $movie = amodb("/movie/$id", ['language' => $lang]);
    $movie['text_language'] = $lang;
    if (trim($movie['overview'] ?? '') === '') {
        $fallback = amodb("/movie/$id", ['language' => 'en-US']);
        $movie['overview'] = $fallback['overview'] ?? '';
        $movie['text_language'] = 'en-US';
    }
    return $movie;
}

$movie = localizedMovie(550, 'be-BY');
echo $movie['title'], ' (', $movie['original_title'], ')', PHP_EOL;
echo '[', $movie['text_language'], '] ', $movie['overview'], PHP_EOL;
```

תגובה עבור `language=ru-RU`, מקוצרת לכמה שדות. המפתח `text_language` בדוגמת ה-PHP מתווסף על ידי הקוד שלכם, לא על ידי ה-API.

```json
{
  "genres": [
    {
      "id": 18,
      "name": "драма"
    },
    {
      "id": 53,
      "name": "триллер"
    }
  ],
  "id": 550,
  "original_language": "en",
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажды в очередной командировке он...",
  "poster_path": "/66RvLrRJTm4J8l3uHXWF09AICol.jpg",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб"
}
```

## גיבוי כשיש שדה ריק

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

1. בקשו את השפה שאתם מציגים.
2. אם שדה ריק, בקשו `en-US` לאותו מזהה, או קראו את הפריט באנגלית מרשימת התרגומים.
3. אם הכותרת ריקה, הציגו את `original_title`.
4. שמרו מאיזו שפה הגיע כל שדה, כדי שתוכלו לנסות שוב מאוחר יותר.

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

## רשימת כל התרגומים של כותר

`GET /3/movie/{movie_id}/translations` מחזיר מערך `translations`, פריט אחד לכל שפה שיש לה נתונים. הרשימה יכולה להיות ארוכה מ-14 השפות המוגשות: ל-Fight Club יש 50 פריטים. השתמשו בה כדי לבנות מחליף שפות, או כדי לשמור את כל הטקסטים של כותר בשורה אחת.

| שדה                                                                             | משמעות                               |
| ------------------------------------------------------------------------------- | ------------------------------------ |
| `iso_639_1`, `iso_3166_1`                                                       | קודי שפה ומדינה                      |
| `english_name`                                                                  | שם השפה באנגלית                      |
| `data.title` (סרטים) או `data.name` (טלוויזיה), `data.overview`, `data.tagline` | טקסט מתורגם, הכותרת יכולה להיות ריקה |
| `data.homepage`, `data.runtime`                                                 | ערכים אופציונליים לתרגום הזה         |

אותה נקודת קצה קיימת לסדרות ולפרקים. פריטי סדרות נושאים `data.name` ובלי `runtime`, ופריטי פרקים נושאים רק `name` ו-`overview`. עבור עונות מוחזרת רשימה ריקה, ולאנשים ולאוספים אין נקודת קצה של תרגומים. פרטים בעמוד [תרגומים](https://amodb.dev/he/translations/). קריאת תרגומים אחת מחליפה עד 14 קריאות פרטים כשרוצים את כל השפות בבת אחת.

## פוסטרים וסרטונים לפי שפה

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

| פרמטר                    | משמש ב-              | דוגמה        |
| ------------------------ | -------------------- | ------------ |
| `include_image_language` | נקודות קצה של תמונות | `ru,en,null` |

נקודות הקצה של סרטונים מחזירות את כל השפות בתגובה אחת ומתעלמות מ-`include_video_language`, ולכן סננו לפי `iso_639_1` בעצמכם. גדלים וה-CDN מפורטים בעמוד [תמונות](https://amodb.dev/he/images-api/).

## עברית וטקסט מימין לשמאל

עברית היא השפה היחידה מימין לשמאל מבין ה-14. טפלו בכך בעמוד, לא בנתונים:

- הגדירו `lang="he"` ו-`dir="rtl"` על האלמנט שמחזיק את הטקסט.
- עטפו כותרות לטיניות בתוך טקסט עברי באלמנט `<bdi>` כדי שסימני פיסוק לא יקפצו לצד הלא נכון.
- השתמשו במאפייני CSS לוגיים כמו `margin-inline-start` במקום left ו-right.

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

| יכולת               | גירוד דפים בעצמכם             | מערך נתונים באנגלית בלבד | amodb                             |
| ------------------- | ----------------------------- | ------------------------ | --------------------------------- |
| שפות                | אזור שפה אחד של האתר בכל בקשה | אנגלית                   | 14 שפות עם `language`             |
| אותו מזהה בין שפות  | כתובות שונות לכל אזור שפה     | לא רלוונטי               | אותו מזהה מספרי בכל מקום          |
| כל התרגומים של כותר | שליפת דף לכל אזור שפה         | לא רלוונטי               | קריאת `translations` אחת          |
| פוסטרים מותאמים     | כתובות תמונה לכל אזור שפה     | ראו במסמכים שלהם         | מסנן `include_image_language`     |
| כותרת מקורית        | ניתוח מטקסט הדף               | ראו במסמכים שלהם         | `original_title`, `original_name` |

## תמחור

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

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

### אילו שפות ה-API מגיש?

ארבע עשרה: אנגלית, רוסית, אוקראינית, בלארוסית, סינית, פורטוגזית, בולגרית, עברית, צ'כית, רומנית, צרפתית, פולנית, איטלקית וספרדית, עם הקודים en ru uk be zh pt bg he cs ro fr pl it es.

### מה קורה אם שולחים תגית שפה שאינה מוגשת?

התגובה חוזרת לאנגלית. תגית כמו ja-JP מחזירה טקסט באנגלית, בעוד הכותרת המקורית ביפנית עדיין מגיעה ב-original_title לסרטים וב-original_name לסדרות.

### אפשר לקבל כל תרגום של כותר בבקשה אחת?

כן. GET /3/movie/{movie_id}/translations מציג פריט אחד לכל שפה שיש לה נתונים, כל אחד עם title, overview, tagline, homepage ו-runtime. לסדרות ולפרקים יש אותה נקודת קצה, עם name במקום title. לעונות, לאנשים ולאוספים אין תרגומים.

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

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

### האם גם פוסטרים מותאמים לשפה?

פוסטרים נושאים תגית שפה. בקשו אותם עם include_image_language, למשל ru,en,null, ודרגו את ההתאמות בקוד. קבצי התמונות מגיעים מ-img.amodb.dev ולא דורשים מפתח.

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

- [שפות](https://amodb.dev/he/languages/): amodb מגיש כותרים, תקצירים ושמות ב-14 שפות. העבירו בפרמטר language תגית בסגנון TMDB כמו ru-RU או pt-BR; כל תגית אחרת חוזרת לאנגלית, בלי שגיאה.
- [API תרגומים](https://amodb.dev/he/translations/): API תרגומים עם נתיבי TMDB v3: קראו בבת אחת את כל הכותרות, התקצירים והסלוגנים שנשמרו לסרט, לסדרה או לפרק, בכל השפות שלהם, עם iso_639_1 ו-english_name.
- [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/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/multilingual-movie-metadata-api/