Usage

To use Wistia API Helper in a project:

from wystia import <API helper class>

Using the methods on the API classes assume your Wistia API token has previously been configured, for example via the environment variable WISTIA_API_TOKEN. The API token is then used globally by all the API classes when making requests to the Wistia API.

Another option is to use the global configure method as shown below:

WistiaDataApi.configure('MY-API-TOKEN')

Sample usage with the Data API:

from wystia import WistiaApi
from wystia.models import SortBy, LanguageCode, Customizations, Private


# Retrieve a list of all projects in the Wistia account,
# sorted A-Z and in ascending order.
projects = WistiaApi.list_all_projects(SortBy.NAME)
project_ids = [p.hashed_id for p in projects]
# Print the project data as a prettified JSON string
print(projects.prettify())

# Retrieve a list of videos for a Wistia project.
# Note: If you don't require asset info (such as ADs) on each
#   video, I suggest calling `list_project` instead.
videos = WistiaApi.list_videos('project-id')

# Retrieve info on a particular video
vd = WistiaApi.get_video('video-id')
# If the video has captions, that won't be included in the `Medias#show`
# response by default, so we'll need a separate API call as below.
# vd.process_captions(
#     WistiaApi.list_captions(real_video_id))
print(vd)

# Update attributes on a media (video), or set a custom thumbnail on the video.
WistiaApi.update_video(
    'video-id',
    thumbnail_media_id='uploaded-thumbnail-id'
)

# Get aggregated stats for a video, such as view count
stats = WistiaApi.get_stats_for_video('video-id')

# Retrieve the customization data for a video
customizations = WistiaApi.get_customizations('video-id')

# Update only specific customizations for a video
# Note the embed options are documented here:
#   https://wistia.com/support/developers/embed-options
sample_embed_options = Customizations(
    player_color='#e7fad1',
    # Hide comments on the media page
    private=Private(show_comments=False)
)
WistiaApi.update_customizations('video-id', sample_embed_options)

# Get the Spanish captions on a video
captions = WistiaApi.get_captions('video-id', LanguageCode.SPANISH)

# Add (or replace) the English captions on a video
WistiaApi.update_captions(
    'video-id',
    LanguageCode.ENGLISH,
    srt_file='path/to/file.srt'
)

… or to upload media via the Upload API:

from wystia import WistiaUploadApi

# Upload a file to a (default) project on Wistia
r = WistiaUploadApi.upload_file('path/to/my-file.mp4')
# Check if the video was successfully uploaded
# assert r.created
# assert r.name == 'my-file.mp4'

# Uploads with a public link to a video, such as
# an S3 pre-signed url.
r = WistiaUploadApi.upload_link('my-s3-link',
                                title='My Video Name',
                                description='My Description')

… you can alternatively retrieve asset info via the public Media Embed link:

from wystia import WistiaEmbedApi

# Get the media embed data
embed_data = WistiaEmbedApi.get_data('video-id')

# Retrieve the source URL of the original media
source_url = WistiaEmbedApi.asset_url(media_data=embed_data)

… when using the Data API, the WistiaHelper can help to further simplify some calls:

from wystia import WistiaHelper

# Check if the video exists in your Wistia account
assert WistiaHelper.video_exists('abc1234567')

# Check if a video's name indicates the video is an archived copy of an
# existing video, as discussed in the below article on replacing a media:
#   https://wistia.com/learn/product-updates/improved-library-management-tools
assert WistiaHelper.is_archived_video(
    'My Title [Archived on August 13, 2015]')

# Update the player color on a video
WistiaHelper.customize_video_on_wistia('video-id', 'ffffcc')

# Individually enable captions / AD in the player for a video
WistiaHelper.enable_ad('video-id')
WistiaHelper.enable_captions('video-id', on_by_default=False)

# Disable captions / AD in the player for a video
if WistiaHelper.has_captions_enabled('video-id'):
    print('Disabling captions and AD for the video')
    WistiaHelper.disable_captions_and_ad('video-id')