# API за постери на филми и CDN за изображения

> Постерите се зареждат от https://img.amodb.dev/t/p/{size}/{file} без API ключ. Частта file е poster_path от всеки отговор за филм, търсене или списък. Имената на размерите вървят от w92 до original, а include_image_language избира постери по език. Само JSON извикванията искат ключа ви.

## Постери на филми от хост за изображения, който не иска ключ

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/bg/images-api/).

## Започнете в 3 стъпки

1. Изберете план на страницата с [цените](https://amodb.dev/bg/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/bg/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/bg/images-api/): API за изображения на филми с пътища на TMDB v3: списъци с постери, фонови изображения, лога и кадри, после зареждане от img.amodb.dev в 10 размера без ключ.
- [API за детайли на филм](https://amodb.dev/bg/movies/): API за детайли на филм със същите пътища и JSON като TMDB v3. Един филм по id, а актьори, рейтинги и настроения през append_to_response, на 14 езика.
- [API за сериали](https://amodb.dev/bg/tv-series/): API за сериали със същите пътища и JSON като TMDB v3. Сериал по id със сезони, мрежи и следващ епизод, плюс възрастови рейтинги и доставчици за гледане.
- [API за търсене](https://amodb.dev/bg/search/): API за търсене със същите пътища и JSON като TMDB v3. Намира филми, сериали, личности, колекции, компании и ключови думи по текст, с филтър по година.
- [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути.
- [Удостоверяване](https://amodb.dev/bg/authentication/): Как да изпратите ключа си за amodb: api_key в заявката, заглавка Authorization с Bearer или apikey за OMDb. Формат, съхранение, смяна на ключ и грешките 401.

Обновено: 2026-10-18. Source: https://amodb.dev/bg/movie-poster-api/