Skip to main content
POST
/
v1
/
understand
/
streamConnect
Start Stream Video Understanding
curl --request POST \
  --url https://stream.memories.ai/v1/understand/streamConnect \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "rtmp://your.server:1935/live/stream",
  "user_prompt": "What is happening right now?",
  "system_prompt": "You are a real-time video monitoring system.",
  "callback": "https://your.app/callback",
  "thinking": false
}
'
{
  "status": 0,
  "task_id": "5347085a-1747-4731-bdde-3856d09502c4",
  "text": ""
}

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 Intelligence — Live Video Understanding Use case: Apply a custom AI prompt continuously to a live RTMP stream (e.g. captioning, activity recognition, custom monitoring), results to your callback every 5s Mode: Server-Pull (you give us an RTMP URL → we pull → results to your callback) Host: https://stream.memories.ai Auth: Authorization: sk-mavi-... (no Bearer prefix)
Start a real-time analysis session on a live RTMP video stream. The server pulls the stream, runs an AI model against each frame window using your custom user_prompt, and pushes results to your callback URL every few seconds.
Each API key supports a maximum of 4 concurrent streaming tasks. Billing occurs every 5 seconds per active stream. If a credit deduction fails, the stream is automatically terminated.

​
Request Example

import requests

url = "https://stream.memories.ai/v1/understand/streamConnect"
headers = {
    "Authorization": "sk-mavi-...",
    "Content-Type": "application/json"
}

payload = {
    "url": "rtmp://your.server/live/stream",
    "user_prompt": "What stage is the food preparation at? Is it ready to eat?",
    "system_prompt": "Track the current cooking progress.",
    "callback": "https://your.app/callback",
    "thinking": False
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())  # {"status": 0, "task_id": "..."}

​
Parameters

​
url
string
required
RTMP stream URL for live video input (e.g. rtmp://your.server:1935/live/stream).
​
user_prompt
string
required
The analysis instruction applied to each frame window — e.g. "What is happening right now?".
​
system_prompt
string
required
Role or context for the AI — e.g. "You are a real-time video monitoring system.".
​
callback
string
required
Public URL to receive continuous analysis results. Called repeatedly throughout the stream lifetime.
​
thinking
boolean
default:"false"
Enable reasoning mode for deeper analysis.

​
Start Stream Response

{
  "status": 0,
  "task_id": "5347085a-1747-4731-bdde-3856d09502c4",
  "text": ""
}
Use the returned task_id to stop the stream via Stop Stream Video Understanding.

​
Callback Payload

Results are pushed to your callback URL continuously while the stream is active: 
{
  "status": 0,
  "task_id": "5347085a-1747-4731-bdde-3856d09502c4",
  "data": {
    "text": "The chef is frying vegetables. The dish appears to be halfway done.",
    "timestamp": "2025-10-22T12:00:45Z"
  }
}
​
status
integer
0 = success, -1 = failure.
​
task_id
string
Identifies which stream this callback belongs to. Use this to stop the stream.
​
data.text
string
AI-generated analysis for the current frame window.
​
data.timestamp
string
UTC timestamp of the analysis frame.

​
Error Codes

CodeMeaning
-1Invalid request or parameters
1001Maximum concurrent streams reached (4 per key)
2001Credit deduction failed — stream auto-terminated
5000Internal server error

​
Billing

  • Charged every 5 seconds per active stream
  • If credit deduction fails, the stream stops automatically — recharge and call this endpoint again to resume
  • This API does not support video file uploads or historical playback — live RTMP only

Authorizations

​
Authorization
string
header
required

Body

application/json
​
url
string
required

RTMP stream URL for live video input

Example:

"rtmp://your.server:1935/live/stream"

​
user_prompt
string
required

Analysis instruction applied to each frame window

Example:

"What is happening right now?"

​
system_prompt
string
required

Role or context for the AI

Example:

"You are a real-time video monitoring system."

​
callback
string
required

Public URL to receive continuous analysis results

Example:

"https://your.app/callback"

​
thinking
boolean
default:false

Enable reasoning mode for deeper analysis

Response

200 - application/json

Stream started successfully

​
status
integer
Example:

0

​
task_id
string
Example:

"5347085a-1747-4731-bdde-3856d09502c4"

​
text
string
Example:

""