# API постэраў фільмаў і CDN выяў

> Постэры загружаюцца з https://img.amodb.dev/t/p/{size}/{file} без ключа API. Частка file гэта poster_path з любога адказу па фільме, пошуку або спісе. Назвы памераў ідуць ад w92 да original, а include_image_language выбірае постэры па мове. Ключ патрэбны толькі для выклікаў JSON, а самі выявы кэшуюцца на 30 дзён.

## Постэры фільмаў з хоста выяў, якому не патрэбны ключ

URL постэра мае выгляд `https://img.amodb.dev/t/p/{size}/{file}`. Частка file гэта радок `poster_path` з любога адказу па фільме, пошуку або спісе, і ён пачынаецца з косай рыскі. Частка size гэта назва, напрыклад `w342`. Выявам ключ не патрэбны, таму браўзеры і праграмы могуць загружаць іх наўпрост. JSON, які называе імя файла, усё яшчэ патрабуе ваш ключ, а amodb гэта незалежнае API, якое працуе па пратаколе TMDB v3, таму існуючы код для выяў працягвае працаваць пасля змены хоста.

Што вы атрымліваеце:

- Постэры, фонавыя выявы, лагатыпы, фота профіляў і кадры эпізодаў на адным хосце.
- Дзесяць назваў памераў, ад `w92` да `original`.
- Спісы постэраў па назве з мовай, шырынёй і вышынёй у кожным элеменце.
- 30-дзённы edge-кэш для выяў.

## Якія даныя вы атрымліваеце

| Выява                           | Імя файла бярэцца з                              | Тыповыя памеры                                            |
| ------------------------------- | ------------------------------------------------ | --------------------------------------------------------- |
| Постэр фільма                   | `poster_path` у `/3/movie/{movie_id}` і ў спісах | `w92`, `w154`, `w185`, `w342`, `w500`, `w780`, `original` |
| Фонавая выява                   | `backdrop_path`                                  | `w300`, `w780`, `w1280`, `original`                       |
| Фота персоны                    | `profile_path` у `/3/person/{person_id}`         | `w185`, `h632`, `original`                                |
| Лагатып кампаніі або тэлеканала | `logo_path`                                      | `w92`, `w154`, `w185`, `w300`, `w500`, `original`         |
| Кадр эпізода                    | `still_path`                                     | `w92`, `w185`, `w300`, `original`                         |
| Усе постэры адной назвы         | `GET /3/movie/{movie_id}/images`                 | Масіў `posters`                                           |

Серыялы, сезоны і калекцыі таксама маюць `poster_path`. Дакладныя спісы памераў чытайце адзін раз пры старце з блока `images` у `GET /3/configuration`, а не задавайце іх жорстка. Даведнік па выявах ёсць на старонцы [выявы](https://amodb.dev/be/images-api/).

## Пачніце за 3 крокі

1. Абярыце план на старонцы [цэны](https://amodb.dev/be/pricing/). Ён вызначае частату выклікаў JSON: 20, 40 або 120 запытаў у хвіліну.
2. Стварыце ключ у асабістым кабінеце.
3. Прачытайце `poster_path` з выкліку дэталяў або спісу, потым змясціце яго за хост выяў і назву памеру.

## Прыклад запыту

Праграма на Go пералічвае постэры The Matrix (id фільма 603) па-англійску і без тэксту, выбірае самы шырокі, друкуе гатовы `srcset` і захоўвае файл `w342`. Ключ ідзе толькі ў выклік JSON.

```bash
# the JSON call needs the key
curl -s "https://api.amodb.dev/3/movie/603/images?include_image_language=en,null" \
  -H "Authorization: Bearer $AMODB_KEY"

# the image call does not
curl -s -o poster.jpg "https://img.amodb.dev/t/p/w342/aOIuZAjPaRIE6CMzbazvcHuHXDc.jpg"
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
	"time"
)

const imgBase = "https://img.amodb.dev/t/p/"

type poster struct {
	FilePath string  `json:"file_path"`
	Lang     *string `json:"iso_639_1"`
	Width    int     `json:"width"`
}

type images struct {
	Posters []poster `json:"posters"`
}

func srcset(file string) string {
	var parts []string
	for _, w := range []int{185, 342, 500, 780} {
		parts = append(parts, fmt.Sprintf("%sw%d%s %dw", imgBase, w, file, w))
	}
	return strings.Join(parts, ", ")
}

func main() {
	client := &http.Client{Timeout: 10 * time.Second}

	url := "https://api.amodb.dev/3/movie/603/images?include_image_language=en,null"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}

	var imgs images
	if err := json.NewDecoder(res.Body).Decode(&imgs); err != nil {
		panic(err)
	}
	if len(imgs.Posters) == 0 {
		fmt.Println("no posters")
		return
	}

	best := imgs.Posters[0]
	for _, p := range imgs.Posters {
		if p.Width > best.Width {
			best = p
		}
	}
	lang := "none"
	if best.Lang != nil {
		lang = *best.Lang
	}
	fmt.Println("best poster:", best.FilePath, "language:", lang, "width:", best.Width)
	fmt.Println("srcset:", srcset(best.FilePath))

	// Image requests carry no key.
	pic, err := client.Get(imgBase + "w342" + best.FilePath)
	if err != nil {
		panic(err)
	}
	defer pic.Body.Close()
	if pic.StatusCode != http.StatusOK {
		panic(pic.Status)
	}
	out, err := os.Create("poster.jpg")
	if err != nil {
		panic(err)
	}
	defer out.Close()
	io.Copy(out, pic.Body)
}
```

Скарочаны адказ па выявах для `include_image_language=en,null`: 3 з 145 постэраў, англійскі, самы шырокі англійскі і без тэксту. У адказе таксама ёсць `backdrops` і `logos`, якія тут прапушчаны.

```json
{
  "id": 603,
  "posters": [
    {
      "aspect_ratio": 0.667,
      "height": 2250,
      "iso_639_1": "en",
      "file_path": "/dXNAPwY7VrqMAo51EKhhCJfaGb5.jpg",
      "vote_average": 0,
      "vote_count": 0,
      "width": 1500
    },
    {
      "aspect_ratio": 0.667,
      "height": 3000,
      "iso_639_1": "en",
      "file_path": "/aOIuZAjPaRIE6CMzbazvcHuHXDc.jpg",
      "vote_average": 0,
      "vote_count": 0,
      "width": 2000
    },
    {
      "aspect_ratio": 0.701,
      "height": 1426,
      "iso_639_1": null,
      "file_path": "/iLWzJxatuwwMT76dtMuwh3FEp2X.jpg",
      "vote_average": 0,
      "vote_count": 0,
      "width": 1000
    }
  ]
}
```

## Выбар памеру

Лік у памеры `w` гэта шырыня выявы ў пікселях, а `h632` гэта вышыня. Малыя назвы эканомяць трафік, вялікія захоўваюць дэталі на шчыльных экранах.

| Памер          | Тыповае выкарыстанне                       |
| -------------- | ------------------------------------------ |
| `w92`          | Падказкі пошуку і малюсенькія радкі спісаў |
| `w154`, `w185` | Шчыльныя спісы і карткі                    |
| `w342`         | Плітка сеткі на тэлефонах                  |
| `w500`         | Старонка з дэталямі                        |
| `w780`         | Вялікія экраны і дысплеі 2x                |
| `original`     | Архіў або друк, немаштабаваны файл         |

Дайце браўзеру некалькі шырынь, і хай ён выбірае. Праграма на Go вышэй друкуе `srcset` з кандыдатамі `185w`, `342w`, `500w` і `780w`. Спалучайце яго з атрыбутам `sizes`, што адпавядае вашаму макету, напрыклад `sizes="(max-width: 600px) 45vw, 185px"` на элеменце `img`.

## Мовы постэраў

Кожны элемент у `posters` мае значэнне `iso_639_1`, або код мовы, або null для афармлення без тэксту. Параметр `include_image_language` прымае спіс кодаў праз коску.

| Значэнне  | Што вяртае                              |
| --------- | --------------------------------------- |
| `en`      | Постэры з пазнакай англійскай           |
| `en,null` | Англійскія постэры і постэры без тэксту |
| `null`    | Толькі постэры без тэксту               |

Добры парадак запасных варыянтаў такі: постэр на мове карыстальніка, потым без тэксту, потым англійскі. Унутры кожнай групы сартуйце па `width` і пры роўнасці бярыце першы. `vote_average` і `vote_count` роўныя `0` у выяў фільмаў і серыялаў, таму нічога не ранжыруюць. Мовы постэраў апісваюць тэкст, надрукаваны на афармленні, таму не залежаць ад 14 моў інтэрфейсу. Правярайце `iso_639_1` у атрыманага, бо набор залежыць ад назвы.

## Захоўванне і кэшаванне постэраў

- Захоўвайце `poster_path`, а не поўны URL. З яго потым можна скласці любы памер.
- Edge кэшуе выявы 30 дзён. Дэталі кэшуюцца 6 гадзін, таму пасля гэтага зноў чытайце `poster_path`, каб убачыць, ці змяніўся ён.
- Трымайце ключ на сваім серверы. Браўзеру адпраўляйце толькі URL выяў.
- Калі `poster_path` роўны null, адлюстроўвайце запаўняльнік замест зламанай выявы.

## Параўнанне

| Магчымасць        | Скрэйпінг старонак дзеля выяў       | Уласныя копіі на сваім хостынгу | Хост выяў amodb                                        |
| ----------------- | ----------------------------------- | ------------------------------- | ------------------------------------------------------ |
| Патрэбны ключ     | Не, дзейнічаюць умовы кожнага сайта | Не                              | Для выяў ключ не патрэбны                              |
| Варыянты памераў  | Той памер, які аддае старонка       | Вы ствараеце і захоўваеце кожны | Фіксаваныя назвы памераў у URL, ад `w92` да `original` |
| Пошук файла       | Разбор HTML                         | Ваша база даных                 | `poster_path` у кожным адказе                          |
| Мовы афармлення   | Старонка за старонкай               | Тое, што вы сабралі             | `include_image_language` на эндпоінтах выяў            |
| Сховішча і трафік | Вашыя, плюс крыніцы                 | Вашыя                           | Браўзер загружае з `img.amodb.dev`                     |
| Кэш               | Ваш                                 | Ваш                             | 30 дзён на edge                                        |

## Цэны

Спампоўкі выяў не маюць ключа. Ваш план абмяжоўвае толькі выклікі JSON, што даюць імёны файлаў, а адказы спісаў ужо ўключаюць `poster_path` для кожнага элемента, таму адзін выклік спіса запаўняе цэлую сетку. Абярыце 20, 40 або 120 запытаў у хвіліну на старонцы [цэны](https://amodb.dev/be/pricing/). Доступ аплачваецца наперад на 1, 3, 6, 12 або 24 месяцы са зніжкай 0, 10, 20, 30 і 40 працэнтаў, нічога не прадаўжаецца само, і бясплатнага тарыфа няма.

## Пытанні і адказы

### Ці патрабуе спампоўка постэраў ключ API?

Не. Выявы прыходзяць з https://img.amodb.dev/t/p/{size}/{file} без ключа, таму браўзер можа загружаць іх наўпрост. Ключ выкарыстоўваюць толькі выклікі JSON, што вяртаюць poster_path.

### Якія памеры постэраў даступныя?

Назвы памераў: w92, w154, w185, w300, w342, w500, w780, w1280, h632 і original. Якія з іх пасуюць да тыпу выявы, пералічана ў блоку images у GET /3/configuration.

### Як атрымаць постэр на пэўнай мове?

Выклічце /3/movie/{id}/images?include_image_language=en,null і прачытайце iso_639_1 у кожнага постэра. Значэнне null пазначае афармленне без тэксту. Потым выбірайце па шырыні. vote_average і vote_count роўныя 0 у выяў фільмаў і серыялаў.

### Як доўга кэшуюцца выявы?

Edge захоўвае выявы 30 дзён. Захоўвайце значэнне poster_path, а не поўны URL, каб потым можна было скласці любы іншы памер без новага запыту.

### Што паказваць, калі poster_path роўны null?

У некаторых назваў няма постэра. Паказвайце запаўняльнік са свайго дызайну, а перад адмовай можна выклікаць эндпоінт выяў, каб пашукаць іншыя постэры.

## Звязаныя старонкі

- [API выяў і хост выяў](https://amodb.dev/be/images-api/): API выяў фільмаў з шляхамі TMDB v3: спісы постэраў, фонавых выяў, лагатыпаў і кадраў назвы, а потым загрузка з img.amodb.dev у 10 памерах без ключа.
- [API дэталяў фільма](https://amodb.dev/be/movies/): API дэталяў фільма з тымі ж шляхамі і JSON, што ў TMDB v3. Адзін фільм па id, а акцёры, рэйтынгі і настрой праз append_to_response, на 14 мовах.
- [API серыялаў](https://amodb.dev/be/tv-series/): API серыялаў з тымі ж шляхамі і JSON, што ў TMDB v3. Серыял па id з сезонамі, тэлеканаламі і наступным эпізодам, плюс узроставыя рэйтынгі і сэрвісы прагляду.
- [API пошуку](https://amodb.dev/be/search/): API пошуку з шляхамі і JSON як у TMDB v3. Фільмы, серыялы, персоны, калекцыі, кампаніі і ключавыя словы па тэксце, з фільтрамі па годзе і старонкамі.
- [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны.
- [Аўтэнтыфікацыя](https://amodb.dev/be/authentication/): Як перадаваць ключ amodb: api_key у запыце, загаловак Authorization Bearer або apikey для выклікаў OMDb. Фармат ключа, захоўванне, замена і памылкі 401.

Абноўлена: 2026-10-18. Source: https://amodb.dev/be/movie-poster-api/