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

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

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. Дакладныя спісы памераў чытайце адзін раз пры старце з блока images у GET /3/configuration, а не задавайце іх жорстка. Даведнік па выявах ёсць на старонцы выявы.

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

1. Абярыце план на старонцы цэны. Ён вызначае частату выклікаў JSON: 20, 40 або 120 запытаў у хвіліну.
2. Стварыце ключ у асабістым кабінеце.
3. Прачытайце poster_path з выкліку дэталяў або спісу, потым змясціце яго за хост выяў і назву памеру.

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

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

# 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"

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, якія тут прапушчаны.

{
  "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 гэта вышыня. Малыя назвы эканомяць трафік, вялікія захоўваюць дэталі на шчыльных экранах.

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

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

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

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

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

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

Параўнанне

Цэны

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