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.

Product: Visual Search Use case: Upload videos and images, auto-index them, then search by natural language, image, or transcript phrase Host: https://api.memories.ai/serve/api/v1 Auth: Authorization: sk-mavi-... (no Bearer prefix)
Pull a video from a publicly reachable URL (mp4 or m3u8) into your Private Video Library for indexing and search. For uploading a local file, use Upload Video — from File. To import from a social platform (TikTok / YouTube / Instagram), use Upload from Social Media.

​
Prerequisites

  • You have created a memories.ai API key.
  • The video URL is publicly accessible via unauthenticated HTTP GET — the server fetches it at request time, so temporary or expiring links may fail.
  • Video codecs: h264, h265, vp9, hevc. m3u8 streams are supported only if all internal paths are fully absolute.
  • Max file size: 1 GB; files larger than 1 GB require special account permission — contact support.

​
Request Example

Uses application/x-www-form-urlencoded. Send parameters as form fields, not JSON.
import requests

headers = {"Authorization": "sk-mavi-..."}
response = requests.post(
    "https://api.memories.ai/serve/api/v1/upload_url",
    headers=headers,
    data={
        "url": "https://example.com/video.mp4",
        "unique_id": "my-project",
        "callback": "https://your.app/callback",
        "datetime_taken": "2025-10-20 11:00:00",
        "camera_model": "Canon EOS 5D",
        "latitude": "39.9042",
        "longitude": "116.4074",
        "tags": ["tag1", "tag2"],
        "retain_original_video": True,
        "video_transcription_prompt": "Focus on spoken dialogue"
    }
)
print(response.json())

​
Parameters

​
url
string
required
Direct URL to the video. Must be publicly accessible via unauthenticated HTTP GET. The server fetches from this URL at request time — ensure it remains available until download starts.
​
unique_id
string
default:"default"
Namespace to group videos under a logical folder in your account. Created automatically on first use. Must be non-empty when provided.
​
callback
string
URL that receives a POST notification when the video finishes indexing. Maximum 299 characters.
​
datetime_taken
string
Capture time in yyyy-MM-dd HH:mm:ss format. Invalid formats are rejected.
​
camera_model
string
Camera or device model name. Maximum 200 characters.
​
latitude
number
GPS latitude where the video was captured (decimal).
​
longitude
number
GPS longitude where the video was captured (decimal).
​
tags
array
User-defined tags. Maximum 20 tags. An api tag is appended automatically.
​
retain_original_video
boolean
default:"true"
Whether to retain the original video file after indexing.
​
video_transcription_prompt
string
Custom prompt to steer the transcription and video understanding focus.

​
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.
​
msg
string
Human-readable status message.
​
data.videoNo
string
Unique identifier for the uploaded video. Use this in all subsequent operations.
​
data.videoName
string
Internal name assigned to the stored video.
​
data.videoStatus
string
Initial processing status. Always UNPARSE immediately after upload; transitions to PARSE once indexing completes.
​
data.uploadTime
string
Upload timestamp in milliseconds since epoch.

​
Knowing When Indexing Is Done

The response returns immediately with videoStatus: "UNPARSE" — the video is queued for indexing but is not yet searchable. Two ways to wait for PARSE:
ApproachHow
PushProvide a callback URL on upload; memories.ai POSTs to it when indexing completes.
PollCall Get Metadata with video_no=<the videoNo above> and check data.status until it becomes PARSE.
Do not use Get Task Status — that endpoint is only for batch Upload from Social Media tasks (which return a taskId, not a videoNo).

​
Notes & Limits

  • Source availability: The URL must remain accessible until the server fetches the video. Temporary or expiring links may fail.
  • Rate limiting: Exceeding the per-account upload rate limit returns an error.
  • Concurrent indexing cap: New uploads are rejected once the rolling 2-hour cap is reached.
  • Billing: Each upload deducts credits from your account balance.

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