Upload video from platform URL

Memories.ai supports uploading a video from a video platform. Currently we support any url from TikTok (Youtube, Instagram, Twitter coming soon). When calling this API, we will first download the data from that url and then index it into Memories.ai system.

Example:

https://www.tiktok.com/@cutshall73/video/7543017294226558221

Additional Notes

This page describes two upload APIs:

• Private Library Upload – Add videos to your personal library for use with Video Chat.
• Public Library Upload – Contribute videos to the shared library for use with Video Marketer.

Key Points

• Videos in the private library can be deleted at any time.
• Videos in the public library are permanent and cannot be deleted.
• Once a video (video_url) is uploaded to one library, uploading the same video to the other is free of charge.
• Videos in the public library are visible to all Memories.ai users and are searchable and queryable by everyone. Thank you for your contribution!
• If a video is scraped again, only metadata is updated—no extra download, storage, or indexing cost will be incurred.

Prerequisites

• You’re familiar with the concepts described on the Platform overview page.
• You have created a memories.ai API key.
• The url must be a proper URL that directs users to a TikTok video play page.

Host URL

• https://api.memories.ai

Endpoint 1 (Upload to private library)

POST /serve/api/v1/scraper_url

Endpoint 2 (Upload to public library)

POST /serve/api/v1/scraper_url_public

---

Request Example (upload to private library)

import requests  
headers = {"Authorization": "<API_KEY>"}  # API key  

# Video url details  
payload={
  "tiktok_post_urls": ["https://www.tiktok.com/@cutshall73/video/7543017294226558221","https://www.tiktok.com/@abcnews/video/7543794552365124919"],
  "unique_id": "default",
  "callback_url": "<CALLBACK_URL>",
} 

response = requests.post(  
    "https://api.memories.ai/serve/api/v1/scraper_url",  
    data=data,  
    headers=headers  
)  

print(response.json())  
 

Request Example (upload to public library)

import requests

headers = {
    "Authorization": "<API_KEY>",  # API key
}

payload = {
    "tiktok_post_urls": [
        "https://www.tiktok.com/@cutshall73/video/7543017294226558221",
        "https://www.tiktok.com/@abcnews/video/7543794552365124919"
    ],
    "callback_url": "<CALLBACK_URL>"
}

resp = requests.post(
    "https://api.memories.ai/serve/api/v1/scraper_url_public",
    json=payload,
    headers=headers,
    timeout=60
)

print(resp.json())

Replace the following placeholders:

• API_KEY: Your actual memories.ai API key.
• CALLBACK_URL: A publicly accessible URL where memories.ai can send video status updates.

Callback Notification Payload

If you provide a callBackUri, memories.ai will send a POST request to it once the video has been uploaded or parsed.

{
    "taskId": "4b2d85ea-8b61-4689-96c3-75d907140242_84f9d9b4b6e5940b67e67e2d17ef1f97", 
    "status": "SUCCEEDED"
}

The callback request body includes the following fields:

• videoNo: The unique video number.
• status: The processing status of the video.

The status field can have one of the following values:

• "SUCCEEDED" – The task is successfully created.
• "FAILED" – The task is not created.

Request Body

{
  "tiktok_post_urls": ["https://www.tiktok.com/@cutshall73/video/7543017294226558221","https://www.tiktok.com/@abcnews/video/7543794552365124919"],
  "callback": "test.beeceptor.com",
  "unique_id": "default", // only needed when uploading to private library
}

Request Parameters

Name	Location	Type	Required	Description
Authorization	header	string	Yes	API key, e.g. Authorization: <API_KEY>
tiktok_post_urls	body	array of string	Yes	List of TikTok post URLs to scrape
unique_id	body	string	No	Correlation id; defaults to "default" (only used when uploading to private library)
callback_url	body	string (URL)	No	Callback URI to notify on successful parsing

Response Example

Status code 200

{
    "code": "0000", 
    "msg": "success", 
    "data": {
        "taskId": "31b0fccb-d6f9-4135-922d-1e8828499812_84f9d9b4b6e5940b67e67e2d17ef1f97"
    }, 
    "failed": false, 
    "success": true
}

Response Structure

Name	Type	Required	Description
code	string	Yes	Status code
msg	string	Yes	Message
data	object	Yes	Data object
» taskId	string	Yes	Unique identifier of the uploading task
failed	boolean	Yes	Indicates whether the request failed
success	boolean	Yes	Indicates whether the request succeeded

Usage of callback_url and task_id

• Data indexing is performed asynchronously. When indexing is complete, Memories.ai will send a notification to the callback_url you provided.
• You can also use the task_id to check the task status.
  • If the "video_ids" field in the response is an empty list [], the system is still downloading the video(s) from the platform.
  • If the "video_ids" field contains one or more IDs (e.g., "PI-603068775285264430"), the video(s) have been downloaded and are currently being indexed.