Skip to main content
POST
/
serve
/
api
/
v1
/
scraper_url
Upload Video from Platform URL
curl --request POST \
  --url https://api.memories.ai/serve/api/v1/scraper_url \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "video_urls": [
    "https://www.tiktok.com/@cutshall73/video/7543017294226558221",
    "https://www.tiktok.com/@abcnews/video/7543794552365124919"
  ],
  "tiktok_post_urls": [
    "<string>"
  ],
  "unique_id": "default",
  "callback_url": "https://your.app/callback",
  "quality": "1080"
}
'
{
  "code": "0000",
  "msg": "success",
  "data": {
    "taskId": "31b0fccb-d6f9-4135-922d-1e8828499812"
  },
  "success": true,
  "failed": false
}

Documentation Index

Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

  • You’re familiar with the concepts described on the Platform overview.
  • You have created a memories.ai API key.
  • Each URL must be a proper link to a video post page on a supported platform.
  • All URLs in a single request must come from the same platform (e.g. you cannot mix TikTok and YouTube URLs in one call).
  • For YouTube URLs your account must have sufficient points/credits; otherwise the request is rejected.

​
Host URL

https://api.memories.ai

​
Endpoint

POST /serve/api/v1/scraper_url 
/serve/api/v1/scraper_url

​
Authentication

Pass your API key in the Authorization request header. Requests without a valid API key are rejected. 
Authorization: <API_KEY>

​
Content Type

The endpoint expects a JSON body (application/json). Send parameters as a JSON object.

​
Request Example

import requests

headers = {"Authorization": "<API_KEY>"}
payload = {
    "video_urls": [
        "https://www.tiktok.com/@cutshall73/video/7543017294226558221",
        "https://www.tiktok.com/@abcnews/video/7543794552365124919"
    ],
    "unique_id": "default",
    "callback_url": "<CALLBACK_URL>",
    "quality": "1080"
}
response = requests.post(
    "https://api.memories.ai/serve/api/v1/scraper_url",
    json=payload,
    headers=headers
)
print(response.json())

​
Callback Notification Payload

If you provide callback_url, memories.ai will send POST notifications for the following events:
  1. The scraping task finishes (download complete).
  2. Each video is successfully indexed.
// Task Succeeded
{ "message": "Video has been downloaded...", "taskId": "...", "status": "SUCCEEDED" }

// Indexing Succeeded
{ "videoId": "VI...", "message": "Video indexing succeed", "taskId": "...", "status": "INDEXING_SUCCEEDED" }

​
Request Parameters

​
video_urls
array
required
List of platform video URLs. After merging with tiktok_post_urls (if any), the combined list must be non-empty and contain at most 50 URLs. All URLs must originate from the same platform.
​
tiktok_post_urls
array
Optional list of TikTok post URLs. Merged server-side into video_urls before processing. Counts toward the 50-URL cap.
​
unique_id
string
default:"default"
Scope identifier used to group videos under a logical folder for the authenticated account. If the folder for this unique_id does not exist yet, it is created automatically on the first request. Defaults to "default" when omitted.
​
callback_url
string
Callback URL that will receive POST notifications when the scraping task finishes and when each video finishes indexing.
​
quality
string
default:"360"
Target video resolution. Must be one of "360", "480", "720", "1080", "1440", "2160" (sent as a string). Defaults to "360" when omitted.

​
Notes & Limits

  • Rate limiting: The endpoint is protected by a per-account scraper rate limit. Exceeding the limit returns an error indicating the request has exceeded the limit.
  • Billing: This endpoint is metered — the cost of the request is checked and deducted from your account balance at request time. Insufficient balance will cause the request to fail.
  • Same-origin constraint: All URLs in a single call must belong to the same platform (TikTok, YouTube, Instagram, etc.). Mixed-platform batches are rejected.
  • YouTube credit check: Requests containing YouTube URLs additionally require enough points; otherwise a “not enough points” error is returned.

​
Response Example

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

​
Response Fields

​
code
string
Business status code. 0000 indicates success; any other value indicates an error and msg will describe it.
​
msg
string
Human-readable status message.
​
data.taskId
string
Unique identifier of the scraping task. Use this value in callbacks and follow-up APIs (e.g. retrieving the video IDs produced by the task).

Authorizations

​
Authorization
string
header
required

Body

application/json
​
video_urls
string<uri>[]
required

Platform video URLs. Merged with tiktok_post_urls; combined list must be non-empty and <= 50. All URLs must be from the same platform.

Maximum array length: 50
Example:
[
  "https://www.tiktok.com/@cutshall73/video/7543017294226558221",
  "https://www.tiktok.com/@abcnews/video/7543794552365124919"
]
​
tiktok_post_urls
string<uri>[]

Optional TikTok post URLs. Server merges these into video_urls before processing. Counts toward the 50-URL cap.

​
unique_id
string
default:default

Scope identifier. A folder is auto-created on first use for the authenticated account.

​
callback_url
string<uri>

Callback URL for task-complete and per-video indexing-complete notifications.

Example:

"https://your.app/callback"

​
quality
enum<string>
default:360

Target video resolution. Must be one of 360/480/720/1080/1440/2160 (string).

Available options:
360,
480,
720,
1080,
1440,
2160
Example:

"1080"

Response

200 - application/json

Successful response

​
code
string

Business status code. 0000 indicates success.

Example:

"0000"

​
msg
string
Example:

"success"

​
data
object
Example:
{
  "taskId": "31b0fccb-d6f9-4135-922d-1e8828499812"
}
​
success
boolean
Example:

true

​
failed
boolean
Example:

false