# API plakatów filmowych i CDN obrazów

> Plakaty ładują się z https://img.amodb.dev/t/p/{size}/{file} bez klucza API. Część file to poster_path z dowolnej odpowiedzi z filmem, wyszukiwaniem lub listą. Nazwy rozmiarów biegną od w92 do original, a include_image_language wybiera plakaty według języka. Klucz potrzebny jest tylko do wywołań JSON, które zwracają nazwy plikó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

| Obraz                            | Nazwa pliku pochodzi z                             | Typowe rozmiary                                           |
| -------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| Plakat filmu                     | `poster_path` w `/3/movie/{movie_id}` i na listach | `w92`, `w154`, `w185`, `w342`, `w500`, `w780`, `original` |
| Tło                              | `backdrop_path`                                    | `w300`, `w780`, `w1280`, `original`                       |
| Zdjęcie osoby                    | `profile_path` w `/3/person/{person_id}`           | `w185`, `h632`, `original`                                |
| Logo firmy lub sieci             | `logo_path`                                        | `w92`, `w154`, `w185`, `w300`, `w500`, `original`         |
| Kadr odcinka                     | `still_path`                                       | `w92`, `w185`, `w300`, `original`                         |
| Wszystkie plakaty jednego tytułu | `GET /3/movie/{movie_id}/images`                   | tablica `posters`                                         |

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](https://amodb.dev/pl/images-api/).

## Start w 3 krokach

1. Wybierz plan na stronie [cennik](https://amodb.dev/pl/pricing/). 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.

```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)
}
```

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.

```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
    }
  ]
}
```

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

| Rozmiar        | Typowe użycie                                  |
| -------------- | ---------------------------------------------- |
| `w92`          | Podpowiedzi wyszukiwania i drobne wiersze list |
| `w154`, `w185` | Gęste listy i karty                            |
| `w342`         | Kafelki siatki na telefonach                   |
| `w500`         | Strona szczegółów                              |
| `w780`         | Duże ekrany i wyświetlacze 2x                  |
| `original`     | Archiwum lub druk, plik bez skalowania         |

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.

| Wartość   | Zwraca                            |
| --------- | --------------------------------- |
| `en`      | Plakaty oznaczone jako angielskie |
| `en,null` | Plakaty angielskie i bez tekstu   |
| `null`    | Tylko plakaty bez tekstu          |

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

| Możliwość                 | Scraping stron po obrazy                 | Własne hostowane kopie               | Host obrazów amodb                                  |
| ------------------------- | ---------------------------------------- | ------------------------------------ | --------------------------------------------------- |
| Wymagany klucz            | Brak, obowiązuje regulamin każdej strony | Brak                                 | Obrazy bez klucza                                   |
| Warianty rozmiarów        | Jaki rozmiar poda strona                 | Każdy generujesz i przechowujesz sam | Stałe nazwy rozmiarów w URL, od `w92` do `original` |
| Znalezienie pliku         | Parsować HTML                            | Twoja własna baza danych             | `poster_path` w każdej odpowiedzi                   |
| Języki grafiki            | Strona po stronie                        | Co udało się zebrać                  | `include_image_language` w endpointach obrazów      |
| Przechowywanie i transfer | Twoje oraz źródła                        | Twoje                                | Przeglądarka ładuje z `img.amodb.dev`               |
| Cache                     | Twój                                     | Twój                                 | 30 dni na edge                                      |

## 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](https://amodb.dev/pl/pricing/). 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.

## Pytania i odpowiedzi

### Czy pobieranie plakatów wymaga klucza API?

Nie. Obrazy pochodzą z https://img.amodb.dev/t/p/{size}/{file} bez klucza, więc przeglądarka może je ładować bezpośrednio. Klucza używają tylko wywołania JSON zwracające poster_path.

### Jakie rozmiary plakatów są dostępne?

Nazwy rozmiarów to w92, w154, w185, w300, w342, w500, w780, w1280, h632 i original. Które pasują do danego typu obrazu, wymienia blok images w GET /3/configuration.

### Jak pobrać plakat w danym języku?

Wywołaj /3/movie/{id}/images?include_image_language=en,null i odczytaj iso_639_1 przy każdym plakacie. Wartość null oznacza grafikę bez tekstu. Potem wybieraj według szerokości. vote_average i vote_count wynoszą 0 przy obrazach filmów i seriali.

### Jak długo obrazy są w cache?

Edge trzyma obrazy przez 30 dni. Zapisuj wartość poster_path, nie pełny URL, aby później zbudować dowolny inny rozmiar bez kolejnego zapytania.

### Co pokazać, gdy poster_path ma wartość null?

Niektóre tytuły nie mają plakatu. Pokaż obraz zastępczy z własnego projektu i opcjonalnie wywołaj endpoint obrazów, by poszukać innych plakatów, zanim się poddasz.

## Powiązane strony

- [API obrazów i host obrazów](https://amodb.dev/pl/images-api/): API obrazów filmów ze ścieżkami TMDB v3: wypisz plakaty, tła, loga i kadry każdego tytułu, a potem ładuj je z img.amodb.dev w 10 rozmiarach bez klucza.
- [API szczegółów filmu](https://amodb.dev/pl/movies/): API szczegółów filmu z tymi samymi ścieżkami i JSON co TMDB v3. Pobierz film po ID, dołącz obsadę, oceny i nastroje przez append_to_response, 14 języków.
- [API szczegółów serialu](https://amodb.dev/pl/tv-series/): API szczegółów serialu z tymi samymi ścieżkami i JSON co TMDB v3. Serial po ID z sezonami, sieciami, klasyfikacją wiekową i dostawcami streamingu.
- [API wyszukiwania](https://amodb.dev/pl/search/): API wyszukiwania z tymi samymi ścieżkami i JSON co TMDB v3. Znajdź filmy, seriale, osoby, kolekcje, firmy i słowa kluczowe po tekście, z filtrem roku.
- [Szybki start](https://amodb.dev/pl/quickstart/): Pierwsze wywołanie amodb: zdobądź klucz, pobierz szczegóły filmu w curl, JavaScript, Python, PHP lub Go, potem załaduj plakat z img.amodb.dev. Poniżej 2 minut.
- [Uwierzytelnianie](https://amodb.dev/pl/authentication/): Jak wysłać klucz amodb: api_key w zapytaniu, nagłówek Authorization Bearer albo apikey dla wywołań OMDb. Format klucza, przechowywanie, rotacja i błędy 401.

Zaktualizowano: 2026-10-18. Source: https://amodb.dev/pl/movie-poster-api/