API Documentation - venkatasaipunnam/tiktok-api GitHub Wiki

Overview

Provide a brief overview of API's.

Application Base URL

URL:

Session Start

To start the session user need to provide the access code that he received

Endpoint:

POST /session/start/

Request Form Data

Parameter	Type	Description	Requirement
access_key	integer	Access code that user received for participating research experiment	Required
experiment_condition	integer	Which Experiment screen user is doing (1, 2, 3)	Required

Example Request

{
    "access_key": 123456,
    "experiment_code": 1
}

Example Response Data

The API response returns the following JSON structure:

Parameter	Type	Description
session_id	string	Unique identifier for the session.
experiment_condition	integer	Experiment condition identifier.
start_time	string	Start time of the session.
end_time	string	End time of the session.
auth_id	string	Authentication identifier.

{
    "session_id": "117964ca-4793-4db3-b1cf-c18fdca1cd8f",
    "experiment_condition": 1,
    "start_time": "2024-01-27T20:20:35.170732-05:00",
    "end_time": "2024-01-27T20:51:16.982048-05:00",
    "auth_id": "19d8cb41-1e96-4d14-b4a4-5692a347a900"
}

---

Session Save

After finishing the experiment, use session save end point to save the experiment session.

Endpoint:

PUT /session/save/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	Session Unique Id generated when experiment is started	Required
experiment_condition	integer	Which Experiment screen user is finished	Required

Example Request

{
    "session_id":"117964ca-4793-4db3-b1cf-c18fdca1cd8f",
    "experiment_condition":1
}

Example Response Data

The API response returns the following JSON structure:

Parameter	Type	Description
session_id	string	Unique identifier for the session.
experiment_condition	integer	Experiment condition identifier.
start_time	string	Start time of the session.
end_time	string	End time of the session.
auth_id	string	Authentication identifier.

{
    "session_id": "117964ca-4793-4db3-b1cf-c18fdca1cd8f",
    "experiment_condition": 1,
    "start_time": "2024-01-27T20:20:35.170732-05:00",
    "end_time": "2024-01-27T20:31:33-05:00",
    "auth_id": "19d8cb41-1e96-4d14-b4a4-5692a347a900"
}

---

Session Create

After finishing saving the experiment, use create end point to start the next experiment screen.

Endpoint:

POST /session/create/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	Session Unique Id generated when experiment is started	Required
experiment_condition	integer	Next Experiment screen user is Starting	Required

Example Request

{
    "session_id":"117964ca-4793-4db3-b1cf-c18fdca1cd8f",
    "experiment_condition":2
}

Example Response Data

The API response returns the following JSON structure:

Parameter	Type	Description
session_id	string	New Unique identifier for the session.
experiment_condition	integer	Experiment condition identifier.
start_time	string	Start time of the session.
end_time	string	End time of the session.
auth_id	string	Authentication identifier.

{
    "session_id": "6b03ee78-3625-4b99-926f-539c9616af94",
    "experiment_condition": 2,
    "start_time": "2024-01-27T20:31:29.883450-05:00",
    "end_time": "2024-01-27T21:06:10.142601-05:00",
    "auth_id": "19d8cb41-1e96-4d14-b4a4-5692a347a900"
}

---

Get Videos

Fetches List of 10 Video Data based on the hashtags provided and most liked videos. The videos are prioritized based on the user conditions.

Endpoint:

POST /hashtag/videos/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	New Unique identifier for the session.	Required
hashtags	List[string]	List of 5 Hashtags User choose	Required

Example Request

{
    "session_id": "6b03ee78-3625-4b99-926f-539c9616af94",
    "hashtags": ["mining", "nfl", "49ers", "Chiefs", "chef"]
}

Example Response Data

The API response returns the following JSON structure:

Field	Type	Description
video_id	string	Unique identifier for the video.
description	string	Description of the video.
hashtag_name	string	Hashtag Name that are lined to the video
user_name	string	User name associated with the video.
music_id	string	Unique identifier for the associated music.
duration	integer	Duration of the video in seconds.
like_count	integer	Number of Liked the video had
view_count	integer	Number of Views the video had
video_url	string	mp4 video url fetched from the rapid API
Priority	integer	Priority of the video set based on the user conditions

[
    {
        "video_id": "7334862587059817771",
        "description": "Even the national guard couldn’t get me off him #jakegyllenhaal #jakegyllenhaaledit #beyonce #bloomsdarko ",
        "hashtag_name": "beyonce",
        "duration": 19,
        "user_name": "bloomsdarko",
        "music_id": "7318518224763603755",
        "like_count": 9290,
        "view_count": 1735,
        "video_url": "https://video_url.net",
        "Priority": 0
    }
]

---

Get Video by video id

Fetches Video Data based on the video id provided video URL will be fetched on request

Endpoint:

POST /videos/id/

Request Form Data

Parameter	Type	Description	Requirement
video_id	string	Video unique Id specific to each video	Required
session_id	string	New Unique identifier for the session.	Required

Example Request

{
    "session_id": "6b03ee78-3625-4b99-926f-539c9616af94",
    "video_id": "7318911919102922026"
}

Example Response Data

The API response returns the following JSON structure:

Field	Type	Description
video_id	string	Unique identifier for the video.
description	string	Description of the video.
user_name	string	User name associated with the video.
create_time	string	Time when the video was created .
music_id	string	Unique identifier for the associated music.
duration	integer	Duration of the video in seconds.
region_code	string	Region code indicating the location (e.g., "US" for the United States).
video_url	string	mp4 video url fetched from the rapid API
video_thumbnail	string	video thumbnail in base64 encoded
is_liked	bool	Is video liked by the user

{
    "video_id": "7318911919102922026",
    "description": "RUSSELL WILSON MAY NOT BE A BRONCO MUCH LONGER BUT HE IS A CLASS ACT #nba #basketball #k #nfl #sports #lebronjames #lakers #ballislife #mlb #nbabasketball #nike #lebron #nbaplayoffs #jordan #football #kobe #kobebryant #nbafinals #bball #explorepage #dunk #basket #nhl #michaeljordan #espn #explore #hoops #sport #nbanews #nbamemes #tiktok #seattleseahawks #Denver #Broncos #viral #viralvideo ",
    "user_name": "misterfouroneone",
    "create_time": "2024-01-01T04:56:34-05:00",
    "music_id": "'7318912010770860846'",
    "duration": 60,
    "region_code": "US",
    "video_url": "https://example.com/video.mp4",
    "video_thumbnail": "jkjfvjvkjnjbn",
    "is_liked" : false
}

---

Save Participant Interaction

Saves the User Interaction to the individual video

Endpoint:

POST /participant/save/

Request Form Data

Parameter	Type	Description	Requirement
video_id	string	Unique identifier for the video.	Required
session_id	string	Unique identifier for the session.	Required
start_time	string	Start time of the video watching (Format: "YYYY-MM-DD HH:mm:ss").	Required
end_time	string	End time of the video watching (Format: "YYYY-MM-DD HH:mm:ss").	Required
is_liked	boolean	Indicates whether the video is liked (true/false).	Required

Example Request

{
    "video_id": "7318911886475545899",
    "session_id":"6b03ee78-3625-4b99-926f-539c9616af94",
    "start_time": "2024-01-27 20:40:00",
    "end_time": "2024-01-27 20:42:12",
    "is_liked": true
}

Example Response Data

The API response returns the following JSON structure:

Field	Type	Description
watch_id	integer	Unique identifier for the watch event.
start_time	string	Start time of the watch event.
end_time	string	End time of the watch event.
is_liked	boolean	Indicates whether the video is liked (true/false).
session_id	string	Unique identifier for the session associated with the watch event.
video_id	string	Unique identifier for the video.

{
    "watch_id": 5,
    "start_time": "2024-01-28T01:40:00-05:00",
    "end_time": "2024-01-28T01:42:12-05:00",
    "is_liked": true,
    "session_id": "6b03ee78-3625-4b99-926f-539c9616af94",
    "video_id": "'7318911886475545899'"
}

---

Save Experiment Conditions

Saves the Experiment Settings after each interaction with the User

Endpoint:

POST /experiment/save/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	New Unique identifier for the session.	Required
experiment	object	Experiment objects which differ from each experiment	Required

Experiment Condition 1

Parameter	Type	Description	Requirement
page_no	integer	Page no is an int field that specifies which page (1,2,3,4,5)	Required
start_time	string	Start time when the user in interaction page(Format: "YYYY-MM-DD HH:mm:ss")	Required
end_time	string	End time when the user out of the interaction page (Format: "YYYY-MM-DD HH:mm:ss")	Required
hashtag_ratings	object	This field is unique to the Experiment condition 1, Its an objects of Hashtags and ratings	Required

hashtag ratings

Parameter	Type	Description	Requirement
hashtag_name	string	hashtag_name that user chooses at the starting of the experiment	Required
rating	integer	Rating from 1 to 5 (low to high interested)	Required

Experiment Condition 2

Parameter	Type	Description	Requirement
page_no	integer	Page no is an int field that specifies which page (1,2,3,4,5)	Required
start_time	string	Start time when the user in interaction page(Format: "YYYY-MM-DD HH:mm:ss")	Required
end_time	string	End time when the user out of the interaction page (Format: "YYYY-MM-DD HH:mm:ss")	Required
like_status	object	This field is unique to the Experiment condition 1, Its an objects of Hashtags and ratings	Required

like status

Parameter	Type	Description	Requirement
video_id	string	Video which user like status is recording for the experiment	Required
hashtag_name	string	hashtag_name that user chooses at the starting of the experiment	Required
status	integer	Status of the video Liked(1), disliked(-1), neutral(0)	Required

Example Request for Experiment Condition 1

{
    "session_id": "ac054248-7602-487d-9f3e-881fa4816798",
    "experiment":{
        "page_no":1,
        "start_time": "2024-03-06 18:40:00",
        "end_time": "2024-03-06 18:42:23",
        "hashtag_ratings": [
			{"hashtag_name": "49ers", "rating": 3},
			{"hashtag_name": "apple", "rating": 5},
			{"hashtag_name": "beyonce", "rating": 5},
			{"hashtag_name": "chef", "rating": 5},
			{"hashtag_name": "chiefs", "rating": 5}
		]
    }
}

Example Request for Experiment Condition 2

{
    "session_id": "7fd3d7fc-2ca0-41d9-9f46-21dbfe825802",
    "experiment": {
        "page_no": 1,
        "start_time": "2024-03-06 18:40:00",
        "end_time": "2024-03-06 18:42:23",
        "like_status": [
            {
                "video_id": "7334862587059817771",
                "hashtag_name": "beyonce",
                "status": 1
            },
            {
                "video_id": "7334838378220883246",
                "hashtag_name": "chef",
                "status": -1
            },
            {
                "video_id": "7334868347961625902",
                "hashtag_name": "49ers",
                "status": 0
            },
            {
                "video_id": "7334865847019752750",
                "hashtag_name": "beyonce",
                "status": 1
            },
            {
                "video_id": "7334857460563332382",
                "hashtag_name": "chef",
                "status": -1
            },
            {
                "video_id": "7334849807963524395",
                "hashtag_name": "apple",
                "status": 0
            },
            {
                "video_id": "7334864713144110382",
                "hashtag_name": "beyonce",
                "status": 1
            },
            {
                "video_id": "7334866491508034859",
                "hashtag_name": "beyonce",
                "status": 0
            },
            {
                "video_id": "7334868111813791022",
                "hashtag_name": "chiefs",
                "status": 1
            },
            {
                "video_id": "7334865956021341482",
                "hashtag_name": "beyonce",
                "status": 1
            }
        ]
    }
}

Example Response Data

The API response returns the following Same Request JSON structure upon successful:

{
    "session_id": "ac054248-7602-487d-9f3e-881fa4816798",
    "experiment":{
        "page_no":1,
        "start_time": "2024-03-06 18:40:00",
        "end_time": "2024-03-06 18:42:23",
        "hashtag_ratings": [
			{"hashtag_name": "49ers", "rating": 3},
			{"hashtag_name": "apple", "rating": 5},
			{"hashtag_name": "beyonce", "rating": 5},
			{"hashtag_name": "chef", "rating": 5},
			{"hashtag_name": "chiefs", "rating": 5}
		]
    }
}

---

Get Experiment Conditions

Fetches the Experiment Condition based on the session and experiment

Endpoint:

POST /experiment/fetch/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	New Unique identifier for the session.	Required
experiment	object	Experiment objects which differ from each experiment	Required

Experiment Condition 1

Parameter	Type	Description	Requirement
page_no	integer	Page no is an int field that specifies which page (1,2,3,4,5)	Required

Experiment Condition 2

Parameter	Type	Description	Requirement
page_no	integer	Page no is an int field that specifies which page (1,2,3,4,5)	Required
video_ids	List(String)	List of watched 10 video in this page sequence	Required

Example Request for Experiment 1

{
    "session_id": "274c48ce-2a03-4148-a1e3-d56df4847046",
    "experiment":{
        "page_no":1
    }
}

Example Request for Experiment 2

{
    "session_id": "2fca74b1-4f95-4260-a0c9-58b0985edf10",
    "experiment":{
        "page_no":1,
        "video_ids": ["7334862587059817771", "7334838378220883246", "7334868347961625902", "7334865847019752750", "7334857460563332382", "7334849807963524395", "7334864713144110382", "7334866491508034859", "7334868111813791022", "7334865956021341482"]
    }
}

Example Response Data

The API response returns the following JSON structure:

{
    "experiment_condition": 1,
    "experiment": {
        "page_no": 1,
        "hashtag_ratings": [
            {
                "hashtag_name": "49ers",
                "rating": 5
            },
            {
                "hashtag_name": "apple",
                "rating": 5
            },
            {
                "hashtag_name": "beyonce",
                "rating": 5
            },
            {
                "hashtag_name": "chef",
                "rating": 5
            },
            {
                "hashtag_name": "chiefs",
                "rating": 5
            }
        ]
    }
}

{
    "experiment_condition": 2,
    "experiment": {
        "page_no": 1,
        "like_status": [
            {
                "video_id": "7334862587059817771",
                "hashtag_name": "beyonce",
                "status": 1,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334838378220883246",
                "hashtag_name": "chef",
                "status": -1,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334868347961625902",
                "hashtag_name": "49ers",
                "status": 1,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334865847019752750",
                "hashtag_name": "beyonce",
                "status": 1,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334857460563332382",
                "hashtag_name": "chef",
                "status": 1,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334849807963524395",
                "hashtag_name": "apple",
                "status": 0,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334864713144110382",
                "hashtag_name": "beyonce",
                "status": 1,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334866491508034859",
                "hashtag_name": "beyonce",
                "status": 1,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334868111813791022",
                "hashtag_name": "chiefs",
                "status": 0,
                "video_thumbnail":"hbcjdbjbvbbv"
            },
            {
                "video_id": "7334865956021341482",
                "hashtag_name": "beyonce",
                "status": 0,
                "video_thumbnail":"hbcjdbjbvbbv"
            }
        ]
    }
}

---

Experiment Condition 3 Chat API

This API takes input as user message and send it to the OpenAI and generate the response to the User.

Endpoint:

POST /experiment/chat/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	New Unique identifier for the session.	Required
experiment	object	Experiment objects that specific to the Chat	Required

experiment

Parameter	Type	Description	Requirement
page_no	integer	Page no is an int field that specifies which page (1,2,3,4,5)	Required
messages	object	These are the Chat Messages between user and gpt	Required

messages

Parameter	Type	Description	Requirement
user_type	string	the User Type ('user or 'gpt') distinguish between user and gpt messages	Required
content	string	The message that user/gpt sent	Required

Example Request

{
    "session_id": "869a9f75-e92c-41cf-9bcf-19b4e8397c7d",
    "experiment": {
        "page_no": 1,
        "messages": [
            {
                "user_type": "user",
                "content": "No"
            }
        ]
    }
}

Example Response Data

The API response returns the same request by appending the GPT message to it, here is the following JSON structure:

{
    "session_id": "869a9f75-e92c-41cf-9bcf-19b4e8397c7d",
    "experiment": {
        "page_no": 1,
        "messages": [
            {
                "user_type": "user",
                "content": "No"
            },
            {
                "user_type": "gpt",
                "content": "I'm here to help! What types of content would you prefer instead?"
            }
        ]
    }
}

---

Close Experiment Condition 3 Chat API

The Close API save the total time spent on the interaction page/ chat page

Endpoint:

POST /experiment/chat/close/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	New Unique identifier for the session.	Required
experiment	object	Experiment objects that specific to the Chat	Required

experiment

Parameter	Type	Description	Requirement
page_no	integer	Page no is an int field that specifies which page (1,2,3,4,5)	Required
start_time	string	Start time when the user in interaction page(Format: "YYYY-MM-DD HH:mm:ss")	Required
end_time	string	End time when the user out of the interaction page (Format: "YYYY-MM-DD HH:mm:ss")	Required

Example Request

{
    "session_id": "869a9f75-e92c-41cf-9bcf-19b4e8397c7d",
    "experiment": {
        "page_no": 1,
        "start_time": "2024-03-06 18:40:00",
        "end_time": "2024-03-06 18:42:23"
    }
}

Example Response Data

The API response returns the same as request upon successful update, here is the following JSON structure:

{
    "session_id": "869a9f75-e92c-41cf-9bcf-19b4e8397c7d",
    "experiment": {
        "page_no": 1,
        "start_time": "2024-03-06 18:40:00",
        "end_time": "2024-03-06 18:42:23"
    }
}

---

Get Experiment 3 Recommended Videos

Fetches List of 10 Video Data based on the openAI Recommendation

Endpoint:

POST /experiment/recommend/

Request Form Data

Parameter	Type	Description	Requirement
session_id	string	New Unique identifier for the session.	Required

Example Request

{
    "session_id": "b8fe0a56-5039-4b17-aee5-5e3d7d6b57a9"
}

Example Response Data

The API response returns the following JSON structure:

Field	Type	Description
video_id	string	Unique identifier for the video.
description	string	Description of the video.
hashtag_name	string	Hashtag Name that are lined to the video
user_name	string	User name associated with the video.
music_id	string	Unique identifier for the associated music.
duration	integer	Duration of the video in seconds.
like_count	integer	Number of Liked the video had
view_count	integer	Number of Views the video had
video_url	string	mp4 video url fetched from the rapid API
Priority	integer	Priority of the video set based on the user interactions
Recommendation	integer	Recommendation of the videos based on the user interactions

[
    {
        "video_id": "7334862587059817771",
        "description": "Even the national guard couldn’t get me off him #jakegyllenhaal #jakegyllenhaaledit #beyonce #bloomsdarko ",
        "hashtag_name": "beyonce",
        "duration": 19,
        "user_name": "bloomsdarko",
        "music_id": "7318518224763603755",
        "like_count": 9290,
        "view_count": 1735,
        "video_url": "https://video_url.net",
        "Priority": 0,
        "Recommendation": 0
    }
]