Upload video from platform creator URL

Memories.ai supports uploading a number of videos from a video platform's creator. Currently we support any creator url from TikTok, Youtube and Instagram(Facebook, 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:

TikTok: https://www.tiktok.com/@cutshall73
Instagram: https://www.instagram.com/nike/

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

Endpoint 2 (Upload to public library)

POST /serve/api/v1/scraper_public

---

Request Example (upload to private library)

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

# Video url details  
payload={
  "username": "https://www.tiktok.com/@cutshall73",
  "unique_id": "default",
  "scraper_cnt": 4,
  "callback_url": callback,
}

response = requests.post("https://api.memories.ai/serve/api/v1/scraper", headers=headers, json=payload)
print(response.json()) 

Request Example (upload to public library)

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

# Video url details  
payload={
  "username": "https://www.tiktok.com/@cutshall73",
  "scraper_cnt": 4,
  "callback_url": callback,
}

response = requests.post("https://api.memories.ai/serve/api/v1/scraper_public", headers=headers, json=payload)
print(response.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",
  "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_username	body	string / array	Yes	TikTok creator url to scrape the videos from
unique_id	body	string	No	Correlation id; defaults to "default" (only used when uploading to private library)
scraper_cnt	body	int	No	number of most recent videos to index from the creator video list
callback	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.