`twitcaspy.API` — Twitcasting API v2 Reference

class twitcaspy.API(auth=None, *, host='apiv2.twitcasting.tv', parser=None, user_agent=None, signature=None)

Twitcasting API v2.0 Interface

Parameters

auth (AuthHandler) – The authentication handler to be used
host (str) – The general REST API host server URL
parser (Parser) –

The Parser instance to use for parsing the response from Twitcasting.

defaults to an instance of ModelParser
user_agent (str) – The UserAgent to be used
signature (str) – Key to prove that it is a legitimate request in webhook.

Raises

TypeError – If the given parser is not a Parser instance

References

https://apiv2-doc.twitcasting.tv/

Twitcasting API v2 Endpoint	`API` Method
User
GET /users/:user_id	`API.get_user_info()`
GET /verify_credentials	`API.verify_credentials()`
Live Thumbnail
GET /users/:user_id/live/thumbnail	`API.get_live_thumbnail_image()`
Movie
GET /movies/:movie_id	`API.get_movie_info()`
GET /users/:user_id/movies	`API.get_movies_by_user()`
GET /users/:user_id/current_live	`API.get_current_live()`
POST /movies/subtitle	`API.set_current_live_subtitle()`
DELETE /movies/subtitle	`API.unset_current_live_subtitle()`
POST /movies/hashtag	`API.set_current_live_hashtag()`
DELETE /movies/hashtag	`API.unset_current_live_hashtag()`
Comment
GET /movies/:movie_id/comments	`API.get_comments()`
POST /movies/:movie_id/comments	`API.post_comments()`
DELETE /movies/:movie_id/comments/:comment_id	`API.delete_comment()`
Gift
GET /gifts	`API.get_gifts()`
Supporter
GET /users/:user_id/supporting_status	`API.get_supporting_status()`
PUT /support	`API.support_user()`
PUT /unsupport	`API.unsupport_user()`
GET /users/:user_id/supporting	`API.supporting_list()`
GET /users/:user_id/supporters	`API.supporter_list()`
GET /categories	`API.get_categories()`
GET /search/users	`API.search_users()`
GET /search/lives	`API.search_live_movies()`
	`API.incoming_webhook()`
GET /webhooks	`API.get_webhook_list()`
POST /webhooks	`API.register_webhook()`
DELETE /webhooks	`API.remove_webhook()`
GET /rtmp_url	`API.get_rtmp_url()`
GET /webm_url	`API.get_webm_url()`

User

get_user_info

verify_credentials

API.verify_credentials()

Returns application and user information about the access_token.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
app : App
user : User
supporter_count : Raw (int)
supporting_count : Raw (int)

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#verify-credentials

Live Thumbnail

get_live_thumbnail_image

API.get_live_thumbnail_image(*, id=None, screen_id=None, size='small', position='latest')

Returns live thumbnail the specified user.
Returns an offline image if the user is not streaming now.
Either an id or screen_id is required for this method.

Tip

No authentication required.

Parameters

id (str) – The ID of the user. If you specify this parameter, screen_id is ignored.
screen_id (str) – The screen name of the user.(e.g.: @~~)
size(optional) (str) –

image size

’large’ or ‘small’ can be specified.(default is ‘small’.)
position(optional) (str) –

‘beginning’ or ‘latest’ can be specified.(default is ‘latest’.)

Returns

Image data is stored in the content attribute.

Return type

requests.models.Response

Raises

TwitcaspyException – If both id and screen_id are not specified

References

https://apiv2-doc.twitcasting.tv/#get-live-thumbnail-image

Movie

get_movie_info

API.get_movie_info(movie_id)

Returns information about the specified movie.

Parameters

movie_id (str) – The ID of the movie.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movie : Movie
broadcaster : User
tags : Raw (list)
live : Live
The attribute of Live is as follows.
movie : Movie
broadcaster : User
tags : Raw (list)
result.movie is equivalent to` result.live.movie`.

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#get-movie-info

get_movies_by_user

API.get_movies_by_user(*, id=None, screen_id=None, offset=0, limit=20, slice_id=None)

Returns movies of the specified user in descending order of creation date and time.

Either an id or screen_id is required for this method.

Parameters

id (str) – The ID of the user. If you specify this parameter, screen_id is ignored.
screen_id (str) – The screen name of the user.(e.g.: @~~)
offset(optional) (int) –

Position from the beginning

It can be specified in the range of 0 to 1000.(default is 0.)
limit(optional) (int) –

Maximum number of acquisitions

It can be specified in the range of 1 to 50.(default is 20.)

(In some cases, it may return less than the specified number of videos.)
slice_id(optional) (int or None) –

Gets the movie before this slice_id.

It can be specified in the range of 1 or more.

(Not specified by default.[= None])

If you specify this parameter, offset is ignored.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
total_count : Raw (int)
movies : List of Movie

Return type

Result

Raises

TwitcaspyException – If both id and screen_id are not specified

References

https://apiv2-doc.twitcasting.tv/#get-movies-by-user

get_current_live

API.get_current_live(*, id=None, screen_id=None)

Returns live information if the user is streaming now.

Either an id or screen_id is required for this method.

Parameters

id (str) – The ID of the user. If you specify this parameter, screen_id is ignored.
screen_id (str) – The screen name of the user.(e.g.: @~~)

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movie : Movie
broadcaster : User
tags : Raw (list)
live : Live
The attribute of Live is as follows.
movie : Movie
broadcaster : User
tags : Raw (list)
result.movie is equivalent to` result.live.movie`.

Return type

Result

Raises

TwitcaspyException – If both id and screen_id are not specified

References

https://apiv2-doc.twitcasting.tv/#get-current-live

set_current_live_subtitle

API.set_current_live_subtitle(subtitle, *, cut_out=False)

If the user is broadcasting, set a live telop.

Parameters

subtitle (str) –

live telop
cut_out (bool) –

If the subtitle is more than 17 characters, cut out

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movie_id : Raw (str)
The ID of the movie.
subtitle : Raw (str)

Return type

Result

Raises

TwitcaspyException: – When the subtitle is less than one character. When the subtitle is more than 17 characters and cut_out is False.

References

https://apiv2-doc.twitcasting.tv/#set-current-live-subtitle

unset_current_live_subtitle

API.unset_current_live_subtitle()

If the user is broadcasting, unset a live telop.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movie_id : Raw (str)
The ID of the movie.
subtitle : Raw (None)

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#unset-current-live-subtitle

set_current_live_hashtag

API.set_current_live_hashtag(hashtag, *, cut_out=False)

If the user is broadcasting, set a live hashtag.

Parameters

hashtag (str) – live hashtag
cut_out (bool) –

If the hashtag is more than 26 characters, cut out

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movie_id : Raw (str)
The ID of the movie.
hashtag : Raw (str)

Return type

Result

Raises

TwitcaspyException: – When the hashtag is less than one character./ When the hashtag is more than 26 characters and cut_out is False.

References

https://apiv2-doc.twitcasting.tv/#set-current-live-hashtag

unset_current_live_hashtag

API.unset_current_live_hashtag()

If the user is broadcasting, unset a live hashtag.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movie_id : Raw (str)
The ID of the movie.
hashtag : Raw (None)

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#unset-current-live-hashtag

Comment

get_comments

API.get_comments(movie_id, *, offset=0, limit=20, slice_id=None)

Returns comments of the specified movie in descending order of creation date and time.

Parameters

movie_id (str) – The ID of the movie.
offset(optional) (int) –

Position from the beginning

It can be specified in the range of 0 or more.(default is 0.)
limit(optional) (int) –

Maximum number of acquisitions

It can be specified in the range of 1 to 50.(default is 10.)

(In some cases, it may return less than the specified number of videos.)
slice_id(optional) (int or None) –

Gets the comment after this slice_id.

It can be specified in the range of 1 or more.

(Not specified by default.[= None])

If you specify this parameter, offset is ignored.

2018-08-28 update

The minimum value that can be specified for slice_id is now 1.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movie_id : Raw (str)
The ID of the movie.
all_count : Raw (int)
Total number of comments
comments : List of Comment

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#get-comments

post_comment

API.post_comment(movie_id, comment, *, sns='none')

delete_comment

API.delete_comment(movie_id, comment_id)

Delete the comment.
It can be executed only on a user-by-user basis.
As a general rule, the comments that can be deleted are limited to
those that the poster is the same as the user associated
with the access token.
However, if you use the access token of the user who owns the movie,
you can delete the comments posted by other users.

Parameters

movie_id (str) – The ID of the movie.
comment_id (str) – The ID of the comment.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
comment_id : Raw (str)
ID of the deleted comment.

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#delete-comment

Gift

get_gifts

API.get_gifts(*, slice_id=- 1)

Acquire the item sent by the user associated with the access token in the last 10 seconds.

Parameters

slice_id(optional) (int) –

Gets the items sent after this item send ID.

It can be specified in the range of -1 or more.(default is -1.)

Returns

The attribute of Result is as follows.
latelimit : LateLimit
slice_id : Raw (int)
Slice_id to be specified the next time you call the API.
gifts : list of Gift

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#get-gifts

Supporter

get_supporting_status

API.get_supporting_status(target_user_id, *, id=None, screen_id=None)

Gets the status of whether a user is a supporter of another user.

Either an id or screen_id is required for this method.

Parameters

id (str) – The ID of the user. If you specify this parameter, screen_id is ignored.
screen_id (str) – The screen name of the user.(e.g.: @~~)
target_user_id (str) –

target user id or screen_id

Warning

Note that unlike Supporter, there is no supported_time attribute.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
is_supporting : Raw (bool)
The status of whether (id/screen_id) supported target_user_id.
supported : Raw (int)
Unix time stamp of supported datetime
target_user : User
Target user information

Return type

Result

Raises

TwitcaspyException – If both id and screen_id are not specified

References

https://apiv2-doc.twitcasting.tv/#get-supporting-status

support_user

API.support_user(target_user_ids=None)

Become a supporter of the specified user.

Parameters

target_user_ids (list or tuple) –

An array of target user id or screen_id

The number of elements in the array must be 20 or less.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
added_count : Raw (int)
Number of registered supporters.

Return type

Result

Raises

TwitcaspyException – When target_user_ids is not a list or tuple

References

https://apiv2-doc.twitcasting.tv/#support-user

unsupport_user

API.unsupport_user(target_user_ids=None)

Release the supporter status of the specified user.

Parameters

target_user_ids (list or tuple) –

An array of target user id or screen_id

The number of elements in the array must be 20 or less.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
removed_count : Raw (int)
Number of cases where supporters were released.

Return type

Result

Raises

TwitcaspyException – When target_user_ids is not a list or tuple

References

https://apiv2-doc.twitcasting.tv/#support-user

supporting_list

API.supporting_list(*, id=None, screen_id=None, offset=0, limit=20)

Get a list of users supported by the specified user.

Either an id or screen_id is required for this method.

Parameters

id (str) – The ID of the user. If you specify this parameter, screen_id is ignored.
screen_id (str) – The screen name of the user.(e.g.: @~~)
offset(optional) (int) –

Position from the beginning

It can be specified in the range of 0 or more.(default is 0.)
limit(optional) (int) –

Maximum number of acquisitions

It can be specified in the range of 1 to 20.(default is 20.)

(In some cases, it may return less than the specified number of support users.)

Returns

The attribute of Result is as follows.
latelimit : LateLimit
total : Raw (int)
Total number of records.
(It may differ from the actual number that can be obtained)
supporting : list of Supporter

Return type

Result

Raises

TwitcaspyException – If both id and screen_id are not specified

References

https://apiv2-doc.twitcasting.tv/#supporting-list

supporter_list

API.supporter_list(sort='ranking', *, id=None, screen_id=None, offset=0, limit=20)

Get a list of users who support the specified user.

Either an id or screen_id is required for this method.

Parameters

sort (str) –

Sort order

sort must be one of the following:

’new’ : New arrival order

’ranking’ : Contribution order
id (str) – The ID of the user. If you specify this parameter, screen_id is ignored.
screen_id (str) – The screen name of the user.(e.g.: @~~)
offset(optional) (int) –

Position from the beginning

It can be specified in the range of 0 or more.(default is 0.)
limit(optional) (int) –

Maximum number of acquisitions

It can be specified in the range of 1 to 20.(default is 20.)

(In some cases, it may return less than the specified number of support users.)

Returns

The attribute of Result is as follows.
latelimit : LateLimit
total : Raw (int)
Total number of records.
(It may differ from the actual number that can be obtained)
supporters : list of Supporter

Return type

Result

Raises

TwitcaspyException – If both id and screen_id are not specified.
TwitcaspyException – When sort is not a ‘new’ or ‘ranking’.

References

https://apiv2-doc.twitcasting.tv/#supporter-list

Category

get_categories

API.get_categories(lang='ja')

Get only the categories being streamed.

Parameters

lang (str) –

Language to search
lang must be one of the following:
’ja’ : Japanese
’en’ : English

Returns

The attribute of Result is as follows.
latelimit : LateLimit
categories : list of Category

Return type

Result

Raises

TwitcaspyException – When lang is not a ‘ja’ or ‘en’.

References

https://apiv2-doc.twitcasting.tv/#get-categories

Search users and movies

search_users

API.search_users(words, *, limit=10, lang='ja')

Search for users.

Parameters

words (str or list or tuple) –

Multiple words are ANDed by separating them with space.
lang (str) –

Language setting of the user to be searched.

Currently only “ja” is supported.

’ja’ : Japanese
limit(optional) (int) –

Maximum number of acquisitions

It can be specified in the range of 1 to 50.(default is 10.)

(In some cases, it may return less than the specified number of support users.)

Returns

The attribute of Result is as follows.
latelimit : LateLimit
users : list of User

Return type

Result

Raises

TwitcaspyException – When lang is not a ‘ja’.
TwitcaspyException – When words are not specified
TwitcaspyException – When words is not a str, list or tuple

References

https://apiv2-doc.twitcasting.tv/#search-users

search_live_movies

API.search_live_movies(*, type='word', content)

Search for live concerts being streamed.

Parameters

limit(optional) (int) –

Maximum number of acquisitions

It can be specified in the range of 1 to 100.(default is 10.)

(In some cases, it may return less than the specified number of support users.)
type (str) –

Search type

type must be one of the following:

’tag’ : Tag search

’word’ : Word search

’category’ : Subcategory ID match search

’new’ : New Search

’recommend’ : recommend search
context (int, str, list or tuple) –

The type of context is as follows:

When type is tag or word : str, list or tuple

When type is category : int

Not required when type is new or recommend.
lang (str) –

Language setting of the user to be searched.

Currently only “ja” is supported.

’ja’ : Japanese

Returns

The attribute of Result is as follows.
latelimit : LateLimit
movies : list of Live

Return type

Result

Raises

TwitcaspyException – When type are not specified.
TwitcaspyException – When type is not a tag, word, category, new or recommend.
TwitcaspyException – No context specified when type is tag, word or category.
TwitcaspyException – When lang is not a ‘ja’.

References

https://apiv2-doc.twitcasting.tv/#search-live-movies

WebHook

incoming_webhook

API.incoming_webhook(data, secure=True)

Parses notifications to the specified WebHook URL.

Hint

By using the WebHook API, it is possible to notify the distribution start / end event of a specific distributor to the WebHook URL specified in advance. (This sentence was translated by Google Translate.[ja->en])

Tip

No authentication required.

Note

Method : POST

Parameters

data (dict) –

WebHook Payload
secure (bool) –

Enable signature verification function setting.

Returns

The attribute of Result is as follows.
signature : Raw (str)
movie : Movie
broadcaster : User

Return type

Result

Raises

TwitcaspyException – When secure is true and signature do not match.

References

https://apiv2-doc.twitcasting.tv/#incoming-webhook

get_webhook_list

API.get_webhook_list(limit=50, offset=0, user_id)

Get the list of WebHooks associated with the application.

Tip

It can only be executed on an Application-only authentication.

Parameters

limit(optional) (int) –

Maximum number of acquisitions

It can be specified in the range of 1 to 50.(default is 50.)

(In some cases, it may return less than the specified number of webhooks.)
offset(optional) (int) –

Position from the beginning

It can be specified in the range of 0 or more.(default is 0.)
user_id(optional) (str) –

Target user id

Hint

The limit and offset parameters are valid only if user_id is not specified.

Note

For user_id, you can specify a numeric id (e.g.: 182224938) or a character string (e.g.: twitcasting_jp).

Returns

The attribute of Result is as follows.
latelimit : LateLimit
all_count : Raw (int)
Number of registered WebHooks
webhooks : list of WebHook

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#get-webhook-list

register_webhook

API.register_webhook(user_id, event)

Register a new WebHook.

Tip

It can only be executed on an Application-only authentication.

Parameters

user_id (str) –

Target user id
events (list or tuple) –

Event type to hook

The content of the events must be str.

The content of the events must be one of the following:

’livestart’ : Live start

’liveend’ : Live end

Note

For user_id, you can specify a numeric id (e.g.: 182224938) or a character string (e.g.: twitcasting_jp).

Returns

The attribute of Result is as follows.
latelimit : LateLimit
user_id : Raw (str)
User ID
added_events : list of str
Registered event type

Return type

Result

Raises

TwitcaspyException – When events is not a list or tuple
TwitcaspyException – When events is not a livestart, liveend.

References

https://apiv2-doc.twitcasting.tv/#get-webhook-list

remove_webhook

API.remove_webhook(user_id, event)

Remove WebHook.

Tip

It can only be executed on an Application-only authentication.

Parameters

user_id (str) –

Target user id
events (list or tuple) –

Event type to hook

The content of the events must be str.

The content of the events must be one of the following:

’livestart’ : Live start

’liveend’ : Live end

Note

For user_id, you can specify a numeric id (e.g.: 182224938) or a character string (e.g.: twitcasting_jp).

Returns

The attribute of Result is as follows.
latelimit : LateLimit
user_id : Raw (str)
User ID
deleted_events : list of str
Event type to delete hook

Return type

Result

Raises

TwitcaspyException – When events is not a list or tuple
TwitcaspyException – When events is not a livestart, liveend.

References

https://apiv2-doc.twitcasting.tv/#remove-webhook

Broadcasting

get_rtmp_url

API.get_rtmp_url()

Obtain the URL (RTMP) for stream of the user associated with the access token.

Tip

It can only be executed on an non-Application-only authentication.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
enabled : Raw (bool)
Whether RTMP stream is enabled
url : str of None
URL for RTMP stream
stream_key : str or None
RTMP stream key

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#get-rtmp-url

get_webm_url

API.get_webm_url()

Obtain the URL (WebM, WebSocket) for stream of the user associated with the access token.

Tip

It can only be executed on an non-Application-only authentication.

Returns

The attribute of Result is as follows.
latelimit : LateLimit
enabled : Raw (bool)
Whether WebM stream is enabled
url : str or None
URL for WebM stream

Return type

Result

References

https://apiv2-doc.twitcasting.tv/#get-webm-url

twitcaspy.API — Twitcasting API v2 Reference

User

get_user_info

verify_credentials

Live Thumbnail

get_live_thumbnail_image

Movie

get_movie_info

get_movies_by_user

get_current_live

set_current_live_subtitle

unset_current_live_subtitle

set_current_live_hashtag

unset_current_live_hashtag

Comment

get_comments

post_comment

delete_comment

Gift

get_gifts

Supporter

get_supporting_status

support_user

unsupport_user

supporting_list

supporter_list

Category

get_categories

Search users and movies

search_users

search_live_movies

WebHook

incoming_webhook

get_webhook_list

register_webhook

remove_webhook

Broadcasting

get_rtmp_url

get_webm_url

`twitcaspy.API` — Twitcasting API v2 Reference