Skip to main content
POST
/
v1
/
understand
/
streamConnect
Stream Video Understanding API
curl --request POST \
  --url https://stream.memories.ai/v1/understand/streamConnect \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "rtmp://xx.xx.xx.xx:1935/live/livestream",
  "user_prompt": "What stage is the food preparation at? Is it ready to eat?",
  "system_prompt": "Track the current cooking progress.",
  "callback": "https://yourserver.com/callback",
  "thinking": false
}
'
{
  "code": "0000",
  "msg": "success",
  "data": {},
  "success": true,
  "failed": false
}

​
Overview

This API connects to a live video stream, performs AI-based analysis (e.g., status updates, activity recognition, or summarization), and continuously reports results to your provided callback URL. ⚠️ Usage limits:
  • Each API key can open a maximum of 4 concurrent streaming tasks.
  • There is no unique_id concept for this API.
  • Billing occurs every 5 seconds per active stream.
  • If the billing process fails (e.g., insufficient credits), the server will automatically stop the stream.

​
Host URL

https://stream.memories.ai

​
Endpoints

  • POST /v1/understand/streamConnect (Start Stream)
  • POST /v1/understand/stop/{task_id} (Stop Stream)

​
Request Example – Start Stream

import requests, json

url = "https://stream.memories.ai/v1/understand/streamConnect"
headers = { 
    "Authorization": "<API_KEY>", 
    "Content-Type": "application/json"
}
payload = { 
    "url": "rtmp://xx.xx.xx.xx:1935/live/livestream", 
    "system_prompt": "Track the current cooking progress.", 
    "user_prompt": "What stage is the food preparation at? Is it ready to eat?", 
    "callback": "https://yourserver.com/callback", 
    "thinking": False
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

​
Replace the following placeholders:

  • API_KEY: Your valid memories.ai API key.
  • url: RTMP stream address.
  • callback: Endpoint to receive continuous results.

​
Request Example – Stop Stream

import requests

API_KEY = "sk-xxxxx"
BASE_URL = "https://stream.memories.ai/v1/understand"

def stop_task(task_id: str): 
    url = f"{BASE_URL}/stop/{task_id}" 
    headers = { 
        "Authorization": API_KEY, 
        "Content-Type": "application/json" 
    } 
    try: 
        response = requests.post(url, headers=headers, timeout=10) 
        response.raise_for_status() 
        print("✅ Task stopped successfully:") 
        print(response.json()) 
    except requests.exceptions.RequestException as e: 
        print("❌ Request failed:", e)

# Example call
stop_task("5347085a-1747-4731-bdde-3856d09502c4")

​
Request Example - Request Body

{
  "url": "<RTMP_STREAM_URL>",
  "user_prompt": "<USER_PROMPT>",
  "system_prompt": "<SYSTEM_PROMPT>",
  "callback": "<CALLBACK_URL>",
  "thinking": false
}

​
Callback Notification Payload

Results are continuously sent to your provided callback URL during the live stream. Callback Delivery: The system will automatically retry delivering callback notifications up to 5 times until your callback endpoint returns a successful HTTP response (2xx status code). 
{ 
    "status": 0, 
    "task_id": "5347085a-1747-4731-bdde-3856d09502c4", 
    "data": { 
        "text": "The chef is frying vegetables; the dish is halfway done.", 
        "timestamp": "2025-10-22T12:00:45Z" 
    }
}

​
Response Example – Start Stream

Status code: 200 OK 
{ 
    "status": 0, 
    "task_id": "5347085a-1747-4731-bdde-3856d09502c4", 
    "text": ""
}

​
Response Example – Stop Stream

Status code: 200 OK

​
Error Handling

If the streaming endpoint (RTMP endpoint) stops or does not start when the API is called, the task will automatically stop. 
{ 
    "status": 14, 
    "task_id": "5347085a-1747-4731-bdde-3856d09502c4"
}

​
Billing & Quota

  • Billing interval: Every 5 seconds per active stream
  • Credit deduction: Automatic; if deduction fails, the stream terminates automatically
  • Restart after stop: Client must recharge and call /streamConnect again to resume.

Authorizations

​
Authorization
string
header
required

Body

application/json
​
url
string
required
Example:

"rtmp://xx.xx.xx.xx:1935/live/livestream"

​
user_prompt
string
required
Example:

"What stage is the food preparation at? Is it ready to eat?"

​
system_prompt
string
Example:

"Track the current cooking progress."

​
callback
string<uri>
Example:

"https://yourserver.com/callback"

​
thinking
boolean
default:false

Response

200 - application/json

Successful response

​
code
Example:

"0000"

​
msg
string
Example:

"success"

​
data
​
success
boolean
Example:

true

​
failed
boolean
Example:

false