Skip to main content
POST
/
serve
/
api
/
v1
/
upload_url
Upload Video from URL
curl --request POST \
  --url https://api.memories.ai/serve/api/v1/upload_url \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data url=https://example.com/test_video.mp4 \
  --data callback=https://your.app/callback \
  --data unique_id=default \
  --data 'datetime_taken=2025-10-20 11:00:00' \
  --data 'camera_model=Canon EOS 5D' \
  --data latitude=66.66 \
  --data longitude=66.66 \
  --data-urlencode tags%5B0%5D=test1 \
  --data-urlencode tags%5B1%5D=test2 \
  --data retain_original_video=true \
  --data 'video_transcription_prompt=Focus on the speaker and major scene changes.'
{
  "code": "0000",
  "msg": "success",
  "data": {
    "videoNo": "VI568102998803353600",
    "videoName": "1be6a69f3c6e49bf986235d68807ab1f",
    "videoStatus": "UNPARSE",
    "uploadTime": "1744905509814"
  },
  "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.
  • Video and audio codecs: h264, h265, vp9, hevc, or m3u8.
  • Audio track: Required if you intend to use the audio transcription feature.
  • Direct link: The URL must be a direct download link (or stream) reachable via an unauthenticated HTTP GET.

​
Note !!

Only m3u8 files that use fully linked internal absolute paths are supported. Please contact us for permission if the file linked to m3u8 has size > 1GB.

​
Host URL

https://api.memories.ai

​
Endpoint

POST /serve/api/v1/upload_url 
/serve/api/v1/upload_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 form-encoded parameters (application/x-www-form-urlencoded). All parameters are sent as form fields, not as a JSON body.

​
Request Example

import requests

headers = {"Authorization": "<API_KEY>"}
data = {
    "url": "<URL>",
    "callback": "<CallBack URL>",
    "unique_id": "test1020",
    "datetime_taken": "2025-10-20 11:00:00",
    "camera_model": "Canon EOS 5D",
    "latitude": "66.66",
    "longitude": "66.66",
    "tags": ["test1", "test2", "test3", "test4", "test5"],
    "retain_original_video": True,
    "video_transcription_prompt": "<YOUR_CUSTOMIZED_PROMPT_FOR_VIDEO_FOCUS>"
}
response = requests.post(
    "https://api.memories.ai/serve/api/v1/upload_url",
    data=data,
    headers=headers
)
print(response.json())

​
Callback Notification Payload

If you provide a callback, memories.ai will send a POST request to it once the video has been uploaded or parsed. 
{
    "videoNo": "VI554046065381212160",
    "status": "PARSE"
}

​
Request Parameters

​
url
string
required
Direct URL to the video file. Must be non-empty and reachable via unauthenticated HTTP GET (direct download link or stream).
​
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 upload. Must be non-empty when explicitly provided.
​
callback
string
Callback URL that will receive a POST notification when the video moves to the parsing stage. Maximum length 299 characters.
​
datetime_taken
string
Capture time of the video in the exact format yyyy-MM-dd HH:mm:ss (e.g. 2025-10-20 11:00:00). Invalid formats are rejected.
​
camera_model
string
Camera/device model name. Maximum length 200 characters.
​
latitude
number
Latitude where the video was captured. Must be a valid decimal number (e.g. 66.66).
​
longitude
number
Longitude where the video was captured. Must be a valid decimal number (e.g. 66.66).
​
tags
array
List of user-defined tags (e.g. ["test1", "test2"]). Maximum 20 tags per request. The server automatically appends an api tag to every upload.
​
retain_original_video
boolean
default:"true"
Whether to retain the original source video. Defaults to true.
​
video_transcription_prompt
string
Custom prompt that steers the video transcription/understanding focus.

​
Notes & Limits

  • Rate limiting: The endpoint is protected by a per-account upload 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.
  • Source fetch: The server will fetch the video from the provided url; make sure the link is publicly reachable and remains available until parsing starts.

​
Response Example

{
    "code": "0000",
    "msg": "success",
    "data": {
        "videoNo": "VI568102998803353600",
        "videoName": "1be6a69f3c6e49bf986235d68807ab1f",
        "videoStatus": "UNPARSE",
        "uploadTime": "1744905509814"
    }
}

​
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.videoNo
string
Unique identifier assigned to the uploaded video. Use this value for all subsequent operations (status queries, transcription, summary, chat, delete, etc.).
​
data.videoName
string
Internal name assigned to the stored video.
​
data.videoStatus
string
Initial processing status. Typically UNPARSE immediately after upload; the video will transition to parsing asynchronously.
​
data.uploadTime
string
Upload timestamp in milliseconds since epoch (as a string).

Authorizations

​
Authorization
string
header
required

Body

application/x-www-form-urlencoded
​
url
string<uri>
required

Direct URL of the video. Must be reachable via unauthenticated HTTP GET.

Example:

"https://example.com/test_video.mp4"

​
callback
string<uri>

Callback URL invoked when the video moves to the parsing stage. Max 299 characters.

Maximum string length: 299
Example:

"https://your.app/callback"

​
unique_id
string
default:default

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

​
datetime_taken
string

Capture time in format yyyy-MM-dd HH:mm:ss.

Example:

"2025-10-20 11:00:00"

​
camera_model
string

Camera/device model. Max 200 characters.

Maximum string length: 200
Example:

"Canon EOS 5D"

​
latitude
number<double>
Example:

66.66

​
longitude
number<double>
Example:

66.66

​
tags
string[]

User-defined tags. Max 20. The server automatically appends an 'api' tag.

Maximum array length: 20
Example:
["test1", "test2"]
​
retain_original_video
boolean
default:true

Whether to retain the original source video. Defaults to true.

​
video_transcription_prompt
string
Example:

"Focus on the speaker and major scene changes."

Response

200 - application/json

Successful response

​
code
string

Business status code. 0000 indicates success.

Example:

"0000"

​
msg
string
Example:

"success"

​
data
object
Example:
{
  "videoNo": "VI568102998803353600",
  "videoName": "1be6a69f3c6e49bf986235d68807ab1f",
  "videoStatus": "UNPARSE",
  "uploadTime": "1744905509814"
}
​
success
boolean
Example:

true

​
failed
boolean
Example:

false