API לפוסטרים של סרטים ו-CDN לתמונות

פוסטרים של סרטים משרת תמונות שלא דורש מפתח

כתובת של פוסטר היא https://img.amodb.dev/t/p/{size}/{file}. החלק file הוא מחרוזת ה-poster_path מכל תגובה של סרט, חיפוש או רשימה, והיא מתחילה בלוכסן. החלק size הוא שם כמו w342. תמונות לא דורשות מפתח, ולכן דפדפנים ואפליקציות יכולים לטעון אותן ישירות. ה-JSON שאומר לכם מהו שם הקובץ עדיין דורש את המפתח שלכם, ו-amodb הוא API עצמאי שמדבר בפרוטוקול TMDB v3, ולכן קוד תמונות קיים ממשיך לעבוד אחרי החלפת מארח.

מה מקבלים:

• פוסטרים, תמונות רקע, לוגואים, תמונות פרופיל ותמונות סצנה של פרקים באותו מארח.
• עשרה שמות גדלים, מ-w92 עד original.
• רשימות פוסטרים לכל כותר, עם שפה, רוחב וגובה בכל פריט.
• מטמון קצה של 30 יום לתמונות.

אילו נתונים מקבלים

גם לסדרות, לעונות ולאוספים יש poster_path. קראו את רשימות הגדלים המדויקות מבלוק images של GET /3/configuration פעם אחת בהפעלה במקום לקבוע אותן בקוד. הפניית התמונות נמצאת בעמוד תמונות.

מתחילים בשלושה שלבים

1. בחרו מסלול בעמוד תמחור. הוא קובע את הקצב של קריאות ה-JSON: 20, 40 או 120 בקשות לדקה.
2. צרו מפתח בלוח הבקרה של החשבון.
3. קראו את poster_path מקריאת פרטים או רשימה, ואז הציבו אותו מאחורי מארח התמונות ושם גודל.

בקשה לדוגמה

תוכנית ה-Go מציגה את הפוסטרים של The Matrix (מזהה סרט 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)
}

תגובת images מקוצרת עבור 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, לא את הכתובת המלאה. אפשר לבנות ממנו כל גודל מאוחר יותר.
• הקצה שומר תמונות במטמון 30 יום. פרטים נשמרים 6 שעות, ולכן קראו שוב את poster_path אחרי זה כדי לראות אם הוא השתנה.
• השאירו את המפתח בשרת שלכם. שלחו לדפדפן רק את כתובות התמונות.
• כש-poster_path הוא null, הציגו תמונת מחדל במקום תמונה שבורה.

איך זה בהשוואה

תמחור

הורדות תמונות לא נושאות מפתח. המסלול שלכם מגביל רק את קריאות ה-JSON שנותנות לכם שמות קבצים, ותגובות רשימה כבר כוללות poster_path לכל פריט, ולכן קריאת רשימה אחת מזינה רשת שלמה. בחרו 20, 40 או 120 בקשות לדקה בעמוד תמחור. הגישה בתשלום מראש ל-1, 3, 6, 12 או 24 חודשים עם 0, 10, 20, 30 ו-40 אחוז הנחה, שום דבר לא מתחדש מעצמו, ואין מסלול חינמי.