API plakatów filmowych i CDN obrazów

Plakaty filmowe z hosta obrazów niewymagającego klucza

URL plakatu to https://img.amodb.dev/t/p/{size}/{file}. Część file to ciąg poster_path z dowolnej odpowiedzi z filmem, wyszukiwaniem lub listą i zaczyna się od ukośnika. Część size to nazwa taka jak w342. Obrazy nie wymagają klucza, więc przeglądarki i aplikacje mogą ładować je bezpośrednio. JSON, który podaje nazwę pliku, nadal wymaga twojego klucza, a amodb to niezależne API mówiące protokołem TMDB v3, więc istniejący kod do obrazów działa dalej po zmianie hosta.

Co dostajesz:

• Plakaty, tła, loga, zdjęcia profilowe i kadry odcinków na jednym hoście.
• Dziesięć nazw rozmiarów, od w92 do original.
• Listy plakatów dla każdego tytułu, z językiem, szerokością i wysokością przy każdej pozycji.
• Cache na edge dla obrazów przez 30 dni.

Jakie dane dostajesz

Seriale, sezony i kolekcje również niosą poster_path. Dokładne listy rozmiarów odczytaj raz przy starcie z bloku images w GET /3/configuration, zamiast wpisywać je na stałe. Opis obrazów jest na stronie obrazy.

Start w 3 krokach

1. Wybierz plan na stronie cennik. Wyznacza tempo wywołań JSON: 20, 40 lub 120 żądań na minutę.
2. Utwórz klucz w panelu konta.
3. Odczytaj poster_path z wywołania szczegółów lub listy, a potem umieść go za hostem obrazów i nazwą rozmiaru.

Przykładowe żądanie

Program w Go wypisuje plakaty filmu The Matrix (ID filmu 603) po angielsku i bez tekstu, wybiera najszerszy, wypisuje gotowy srcset i zapisuje plik w342. Klucz trafia tylko do wywołania 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)
}

Przycięta odpowiedź z obrazami dla include_image_language=en,null: 3 ze 145 plakatów, angielski, najszerszy angielski i bez tekstu. Odpowiedź zawiera też backdrops i logos, tu pominięte.

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

Wybór rozmiaru

Liczba w rozmiarze w to szerokość obrazu w pikselach, a h632 to wysokość. Małe nazwy oszczędzają transfer, duże zachowują szczegóły na gęstych ekranach.

Daj przeglądarce kilka szerokości i pozwól jej wybrać. Program w Go powyżej wypisuje srcset z kandydatami 185w, 342w, 500w i 780w. Połącz go z atrybutem sizes pasującym do twojego układu, na przykład sizes="(max-width: 600px) 45vw, 185px" na elemencie img.

Języki plakatów

Każda pozycja w posters ma wartość iso_639_1: kod języka albo null dla grafiki bez tekstu. Parametr include_image_language przyjmuje listę kodów oddzielonych przecinkami.

Dobra kolejność zapasowa to plakat w języku użytkownika, potem bez tekstu, potem angielski. W każdej grupie sortuj według width i przy remisie zostaw pierwszy. vote_average i vote_count wynoszą 0 przy obrazach filmów i seriali, więc niczego nie porządkują. Języki plakatów opisują tekst wydrukowany na grafice, więc nie podążają za 14 językami interfejsu. Sprawdź iso_639_1 w tym, co wróci, bo zestaw zależy od tytułu.

Przechowywanie i cache plakatów

• Zapisuj poster_path, a nie pełny URL. Z niego można później zbudować dowolny rozmiar.
• Edge trzyma obrazy w cache przez 30 dni. Szczegóły są w cache przez 6 godzin, więc po tym czasie odczytaj poster_path ponownie, by sprawdzić, czy się zmienił.
• Trzymaj klucz na serwerze. Przeglądarce wysyłaj tylko adresy URL obrazów.
• Gdy poster_path ma wartość null, wyświetl obraz zastępczy zamiast zepsutego obrazu.

Jak wypada w porównaniu

Cennik

Pobieranie obrazów nie wymaga klucza. Twój plan ogranicza tylko wywołania JSON, które dają nazwy plików, a odpowiedzi z listami już zawierają poster_path dla każdej pozycji, więc jedno wywołanie listy zasila całą siatkę. Wybierz 20, 40 lub 120 żądań na minutę na stronie cennik. Dostęp jest przedpłacony na 1, 3, 6, 12 lub 24 miesiące ze zniżką 0, 10, 20, 30 i 40 procent, nic nie odnawia się samo i nie ma darmowego planu.