WIwistia
Captions

List Captions

Changed on

Lists captions belonging to the account. Results can be narrowed to a specific media with media_id, or to several media and languages at once with media_ids[] and languages[]. Each caption includes its text, so combining these filters with pagination fetches transcripts for many media in a few requests. Pass include=metadata to omit transcript text when only track and language information is needed.

Requires api token with one of the following permissions

Read all folder and media data

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token.

An expiring access token created with the all:delegate_to_contact_permissions scope can also be used. It lists only the captions of media it grants the edit-transcripts permission on; no other permission reaches a media's captions.

get/captions

Request

  • Base URL
    https://api.wistia.com/modern
  • URL
    https://api.wistia.com/modern/captions
  • Auth
    HTTP bearer

Query parameters

media_idstring

Find captions for a particular media by providing the media hashed ID

media_ids[]string[]

Find captions belonging to any of these media hashed IDs. IDs that don't match a media the token can access are ignored rather than returning an error.

languages[]string[]

Find captions in any of these languages, using the codes returned in each caption's language field (for example eng or spa). When combined with media_ids[], captions must match both.

include'metadata'

Set to metadata to omit caption text and return only track metadata. Omitting this parameter preserves the existing response, including SRT text.

pageinteger

The page number to retrieve. This cannot be combined with cursor, pagination.

per_pageinteger

The number of medias per page. Use this for both offset pagination and cursor pagination.

enabled0 | 1

If cursor[enabled] is set to 1, the first result set will be fetched with cursor pagination enabled. This values is ignored if cursor[before] or cursor[after] are set.

beforestring

If cursor[before] is set then cursor pagination is enabled and all records before the cursor up to the per_page are returned. This feature is useful for fetching "new records", for example, in a "pull to refersh" feature when showing records in a descending order.

afterstring

If cursor[after] is set then cursor pagination is enabled and all records after the cursor up to the per_page are returned.

If cursor[enabled] is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the per_page. Cursor pagination will also be turned on if cursor[before] or cursor[after] are set. Records returned will have a cursor property set which can be used to fetch more records in the same sort_by ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set.

NOTE: a cursor value is only valid if the sort_by value hasn't changed from the last fetch. For example, you cannot fetch using sort_by id and then pass that cursor value to a sort_by name.

sort_by'id' | 'created' | 'updated' | 'language'

Ordering. When using cursor pagination (see cursor param), only id is supported.

sort_direction0 | 1

Ordering Sort Direction (0 = desc, 1 = asc; default is 1)

Headers

X-Wistia-API-Versionstring required

Response

Captions retrieval successful

english_namestring

English name of the language.

native_namestring

Native name of the language.

languagestring required

A 3 character language code as specified by ISO-639–2.

textstring nullable

The text of the captions for the specified language in SRT format.

is_draftboolean required
idstring required

The unique hashed identifier of the time-coded transcript.

media_idstring required

The hashed ID of the media the captions belong to.

versioninteger nullable required

The active caption payload version, or null when no payload is active.

diarization_status'ready' | 'processing' | 'unavailable' | 'disabled'

Speaker-data availability when include=diarized_segments. Reading a derivable media with no speaker data starts generating it and reports processing; read again shortly for ready. disabled means the account has speaker identification turned off; an account owner or manager can turn it on in Account Settings.

diarization_derivableboolean

Whether speaker data can be generated from the active default transcript when include=diarized_segments. When false, the media stays unavailable.

speaker_data_versioninteger nullable

The concurrency version for speaker assignments when include=diarized_segments, or null when speaker data is unavailable.

cursorstring nullable

A cursor for stable pagination based on current sort_by order. You can pass this to cursor[before] or cursor[after] as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with cursor[enabled], or cursor[before] or cursor[after].

Changes