Skip to main content

​
Audiobook Models

The audiobook models represent audiobook and chapter data from the Spotify API.

​
AudiobookAuthor

Represents an author of an audiobook.

​
Fields

​
name
str
required
The name of the author

​
AudiobookNarrator

Represents a narrator of an audiobook.

​
Fields

​
name
str
required
The name of the narrator

​
ResumePoint

Represents the user’s resume point for a chapter.

​
Fields

​
fully_played
bool
required
Whether the chapter has been fully played by the user
​
resume_position_ms
int
required
The resume position in milliseconds

​
Example JSON

{
  "fully_played": false,
  "resume_position_ms": 125000
}

​
SimplifiedAudiobook

Basic audiobook information embedded in other objects.

​
Fields

​
authors
list[AudiobookAuthor]
required
List of authors of the audiobook
​
available_markets
list[str] | None
A list of ISO 3166-1 alpha-2 country codes where the audiobook is available
​
copyrights
list[Copyright]
required
Copyright statements for the audiobook. See Common Models.
​
description
str
required
Plain text description of the audiobook
​
html_description
str
required
HTML description of the audiobook
​
edition
str | None
The edition of the audiobook (e.g., “Unabridged”)
​
explicit
bool
required
Whether the audiobook contains explicit content
​
external_urls
ExternalUrls
required
External URLs for this audiobook. See Common Models.
​
href
str
required
A link to the Web API endpoint providing full details
​
id
str
required
The Spotify ID for the audiobook
​
images
list[Image]
required
Cover art for the audiobook. See Common Models.
​
languages
list[str]
required
A list of languages the audiobook is available in
​
media_type
str
required
The media type of the audiobook
​
name
str
required
The name of the audiobook
​
narrators
list[AudiobookNarrator]
required
List of narrators of the audiobook
​
publisher
str
required
The publisher of the audiobook
​
type
Literal['audiobook']
required
The object type, always “audiobook”
​
uri
str
required
The Spotify URI for the audiobook
​
total_chapters
int
required
The total number of chapters in the audiobook

​
SimplifiedChapter

Basic chapter information embedded in other objects.

​
Fields

​
audio_preview_url
str | None
A URL to a 30-second preview (MP3) of the chapter
​
available_markets
list[str] | None
A list of country codes where the chapter is available
​
chapter_number
int
required
The number of the chapter
​
description
str
required
Plain text description of the chapter
​
html_description
str
required
HTML description of the chapter
​
duration_ms
int
required
The duration of the chapter in milliseconds
​
explicit
bool
required
Whether the chapter contains explicit content
​
external_urls
ExternalUrls
required
External URLs for this chapter. See Common Models.
​
href
str
required
A link to the Web API endpoint providing full details
​
id
str
required
The Spotify ID for the chapter
​
images
list[Image]
required
Cover art for the chapter. See Common Models.
​
is_playable
bool | None
Whether the chapter is playable in the current market
​
languages
list[str]
required
A list of languages available for the chapter
​
name
str
required
The name of the chapter
​
release_date
str
required
The release date of the chapter
​
release_date_precision
str
required
The precision of the release date: “year”, “month”, or “day”
​
restrictions
Restriction | None
Content restrictions applied to this chapter. See Common Models.
​
resume_point
ResumePoint | None
The user’s resume point for the chapter (only when authenticated)
​
type
Literal['chapter']
required
The object type, always “chapter”
​
uri
str
required
The Spotify URI for the chapter

​
Audiobook

Complete audiobook object with chapter list. Extends SimplifiedAudiobook.

​
Additional Fields

​
chapters
Page[SimplifiedChapter]
required
Paginated list of chapters in the audiobook. See Common Models.

​
Example JSON

{
  "id": "audiobook123",
  "name": "Example Audiobook",
  "authors": [{"name": "Jane Author"}],
  "narrators": [{"name": "John Narrator"}],
  "publisher": "Example Publishing",
  "description": "An example audiobook",
  "html_description": "<p>An example audiobook</p>",
  "edition": "Unabridged",
  "explicit": false,
  "languages": ["en"],
  "media_type": "audio",
  "total_chapters": 12,
  "chapters": {
    "href": "https://api.spotify.com/v1/audiobooks/audiobook123/chapters",
    "items": [
      {
        "id": "chapter1",
        "name": "Chapter 1",
        "chapter_number": 1,
        "duration_ms": 1800000
      }
    ],
    "limit": 50,
    "next": null,
    "offset": 0,
    "previous": null,
    "total": 12
  }
}

​
Chapter

Complete chapter object with audiobook information. Extends SimplifiedChapter.

​
Additional Fields

​
audiobook
SimplifiedAudiobook
required
The audiobook this chapter belongs to

​
Model Relationships

Audiobook Model Hierarchy
  • SimplifiedAudiobook contains basic audiobook metadata, authors, and narrators
  • Audiobook extends SimplifiedAudiobook and includes a Page of SimplifiedChapter objects
  • SimplifiedChapter contains basic chapter information
  • Chapter extends SimplifiedChapter and includes the parent SimplifiedAudiobook
  • ResumePoint tracks user playback progress on chapters

​
Usage Example

from spotify_sdk.models.audiobook import Audiobook, Chapter

# Parse an audiobook from the API response
audiobook = Audiobook(**api_response)

print(f"Audiobook: {audiobook.name}")
print(f"Authors: {', '.join(a.name for a in audiobook.authors)}")
print(f"Narrators: {', '.join(n.name for n in audiobook.narrators)}")
print(f"Total chapters: {audiobook.total_chapters}")

# Iterate through chapters
for chapter in audiobook.chapters.items:
    duration_min = chapter.duration_ms // 60000
    print(f"  Ch {chapter.chapter_number}: {chapter.name} ({duration_min} min)")
    
    # Check resume point if available
    if chapter.resume_point:
        if chapter.resume_point.fully_played:
            print("    ✓ Completed")
        else:
            resume_min = chapter.resume_point.resume_position_ms // 60000
            print(f"    Resume at {resume_min} minutes")

Build docs developers (and LLMs) love

Get started for freeTalk to us