Fanart.tv API (3.2)

The Fanart.tv API provides access to a vast collection of high-quality images for movies, TV shows, and music artists.

Website: https://fanart.tv
Support: Join our Discord community for help and discussions

1. Get your API key
2. Make requests to https://webservice.fanart.tv/{version}/{resource}/{id}?api_key=YOUR_KEY
3. Choose the API version that fits your needs (we recommend v3.2)

The API supports three versions with different response formats:

• v3 (Legacy): Basic image fields without timestamps or dimensions
• v3.1: Adds timestamp (added) field to all images
• v3.2 (Current): Adds dimensions (width, height) and total image count

Key Differences Between Versions

Music API Structure Difference

IMPORTANT: The music API has a fundamental structural difference between versions:

v3 & v3.1 - Albums as Object/Map:

{
  "albums": {
    "album-id-1": { "cdart": [...] },
    "album-id-2": { "cdart": [...] }
  }
}

v3.2 - Albums as Array:

{
  "albums": [
    { "release_group_id": "album-id-1", "cdart": [...] },
    { "release_group_id": "album-id-2", "cdart": [...] }
  ]
}

All endpoints require an API key. There are two types of keys that can be sent either as query parameters or HTTP headers:

Project API Keys (Project Tier)

• Required in most cases - Applications should always send a project key
• For applications and projects (e.g., Plex, Emby, Kodi) that integrate the API
• Query parameter: ?api_key=YOUR_KEY
• HTTP header: api-key: YOUR_KEY
• Get your project key at: https://fanart.tv/get-an-api-key/ (Project API Keys section)
• 7-day delay for access to new images

Personal API Keys (Personal Tier)

• Optional - Can be sent alongside a project key, or used alone
• For end users who want better access to the API (shorter delay for new images)
• Query parameter: ?client_key=YOUR_KEY (takes priority over api_key when both are sent)
• HTTP header: client-key: YOUR_KEY (takes priority over api-key when both are sent)
• Get your personal key at: https://fanart.tv/get-an-api-key/ (Personal API Keys section)
• 2-day delay for access to new images (can be upgraded to VIP for immediate access)

Important for Project Developers: When a personal API key is provided, it bypasses any rate limits applied to the project key and provides better access to newly added images. We strongly recommend that projects allow users to optionally enter their personal API key. This gives users control over their API access and improves their experience with faster access to new content. Direct users to get their personal key in your application's settings.

Authentication Methods

Typical Usage: Project Key Only

# Query parameter
https://webservice.fanart.tv/v3.2/movies/550?api_key=YOUR_PROJECT_KEY

# HTTP header
curl -H "api-key: YOUR_PROJECT_KEY" https://webservice.fanart.tv/v3.2/movies/550

Enhanced Usage: Project Key + Personal Key

# Query parameters (personal key takes priority for tier access)
https://webservice.fanart.tv/v3.2/movies/550?api_key=YOUR_PROJECT_KEY&client_key=YOUR_PERSONAL_KEY

# HTTP headers (personal key takes priority for tier access)
curl -H "api-key: YOUR_PROJECT_KEY" -H "client-key: YOUR_PERSONAL_KEY" https://webservice.fanart.tv/v3.2/movies/550

Alternative: Personal Key Only

# Query parameter
https://webservice.fanart.tv/v3.2/movies/550?client_key=YOUR_PERSONAL_KEY

# HTTP header
curl -H "client-key: YOUR_PERSONAL_KEY" https://webservice.fanart.tv/v3.2/movies/550

Note: When both keys are provided, the personal key determines the access tier (2-day delay instead of 7-day). When both query parameter and header are present for the same key type, the query parameter takes priority.

Different subscription tiers have different access to newly added images:

• VIP: Immediate access to all images (requires VIP membership)
• Personal: 2-day delay for new images (free with client_key - Personal API Key)
• Project: 7-day delay for new images (free with api_key - Project API Key)

All tiers have unlimited image access (no quantity restrictions).

Upgrade to VIP to get immediate access to newly added images! Visit fanart.tv/vip for more information.

The API is designed for high performance and rate limiting is very rarely applied. Most API keys have unlimited access with no rate restrictions.

However, in rare cases where rate limits are configured for specific keys, the API will return HTTP 429 responses. Clients should be prepared to handle these responses gracefully:

• HTTP Status: 429 Too Many Requests
• Retry-After Header: Indicates how many seconds to wait before retrying
• X-RateLimit- Headers*: Provide limit details and remaining quota

Best Practice: Implement exponential backoff when receiving 429 responses, respecting the Retry-After header value.

The rate limiting uses a token bucket algorithm with exponential backoff penalties for repeated violations. If you encounter unexpected rate limiting, please contact support via Discord.

https://webservice.fanart.tv

Movie fanart images

TV show fanart images

Music artist and album images

Recently added images