Skip to main content
POST
/
stream
/
start
Start Video Stream Moderation
curl --request POST \
  --url https://mavi-backend.memories.ai/serve/api/v2/stream/start \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "rtmp://example.com/live/stream",
  "enable_content_moderation": false,
  "enable_logo_detection": false,
  "fps": 1,
  "max_logos": 5
}
'
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Stream processing started successfully"
  }
}
Access Required: To use this API endpoint, please contact us at contact@memories.ai to enable stream processing features for your account.
This endpoint starts real-time video stream processing for content moderation and logo detection. The stream is automatically segmented every 5 seconds, with results sent via webhook callbacks.
Pricing:The pricing varies based on the features enabled:Content Moderation + Logo Detection:
Cost (USD) = duration × 2 × (1 + (fps - 1) × 0.5) / 3600
  • Base rate: $2.00/hour
  • Example (FPS=2): 3.00/hour(3.00/hour (0.00417 per 5-second segment)
Content Moderation Only:
Cost (USD) = duration × 1.5 × (1 + (fps - 1) × 0.5) / 3600
  • Base rate: $1.50/hour
  • Example (FPS=2): 2.25/hour(2.25/hour (0.00313 per 5-second segment)
Logo Detection Only:
Cost (USD) = duration × 1.5 × (1 + (fps - 1) × 0.5) / 3600
  • Base rate: $1.50/hour
  • Example (FPS=2): 2.25/hour(2.25/hour (0.00313 per 5-second segment)
Where:
  • duration: Video duration in seconds (5 seconds per segment)
  • fps: Frames per second
  • Charges occur at start (pre-charge for one segment) and per segment processed

​
Supported Protocols

  • RTMP (Recommended)
  • RTSP

​
Key Features

  • ✅ Real-time stream processing
  • ✅ Automatic 5-second segmentation
  • ✅ Asynchronous webhook callbacks
  • ✅ Content moderation (adult content, violence, etc.)
  • ✅ Logo detection and tracking
  • ✅ Automatic resource management

​
Code Example

import requests

BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2"
API_KEY = "sk-mai-this_a_test_string_please_use_your_generated_key_during_testing"
HEADERS = {
    "Authorization": f"{API_KEY}",
    "Content-Type": "application/json"
}

def start_video_stream(stream_url: str, fps: int = 2):
    url = f"{BASE_URL}/stream/start"
    data = {
        "url": stream_url,
        "enable_content_moderation": True,
        "enable_logo_detection": True,
        "fps": fps,
        "max_logos": 10
    }
    resp = requests.post(url, json=data, headers=HEADERS)
    return resp.json()

# Usage example
result = start_video_stream("rtmp://example.com/live/stream", fps=2)
print(result)
print(f"Task ID: {result['data']['task_id']}")

​
Response

Returns the task information for the started video stream. 
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Stream processing started successfully"
  }
}

​
Request Parameters

ParameterTypeRequiredDefaultDescription
urlstringYes-Video stream URL (supports RTMP/RTSP/HLS)
enable_content_moderationbooleanNofalseEnable content moderation
enable_logo_detectionbooleanNofalseEnable logo detection
fpsintegerNo1Frames per second to process
max_logosintegerNo5Maximum number of logos to detect (1-50)

​
Response Parameters

ParameterTypeDescription
codestringResponse code (200 indicates success)
messagestringResponse message describing the operation result
dataobjectResponse data object containing task information
data.task_idstringUnique identifier of the stream processing task
data.messagestringStatus message about the stream start

​
Callback Response Parameters

Callbacks are sent to your configured webhook URL every time a 5-second segment is processed.
ParameterTypeDescription
codestringResponse code (200 indicates success)
messagestringResponse message (“SUCCESS”)
task_idstringThe task ID associated with this stream
dataobjectWrapper object containing processing results
data.statusintegerStatus code (see Status Codes section below)
data.messagestringStatus message describing the result
data.dataobjectSegment processing results (null for error statuses)
data.data.segment_indexintegerIndex of the processed segment (starts from 0)
data.data.start_timestringSegment start time in seconds
data.data.end_timestringSegment end time in seconds
data.data.video_urlstringURL of the processed video segment
data.data.content_moderationobjectContent moderation results
data.data.content_moderation.has_unsafe_contentbooleanWhether unsafe content was detected
data.data.content_moderation.frames_processedintegerNumber of frames processed
data.data.logo_detectionobjectLogo detection results
data.data.logo_detection.has_logobooleanWhether logos were detected
data.data.logo_detection.logosarrayArray of detected logos (empty if none)
data.data.logo_detection.frames_processedintegerNumber of frames processed
data.data.processing_time_msstringProcessing time in milliseconds
data.tokenobjectToken usage statistics (null for error statuses)
data.token.inputintegerNumber of input tokens used
data.token.outputintegerNumber of output tokens generated
data.token.totalintegerTotal tokens used
data.token.video_tokensintegerTokens from video processing
data.token.text_tokensintegerTokens from text processing

​
Status Codes

StatusNameDescriptionStream Stopped
0SuccessSegment processed successfullyNo
-1ErrorProcessing failedNo
14User StoppedUser manually stopped the streamYes
15No DataStream has no video dataYes
16Capacity ReachedServer capacity limit reachedYes
402Insufficient BalanceUser balance insufficientYes

​
Callback Flow

User Request → Start Stream → Process Segment (every 5s) → Webhook Callback
                    ↓
            Pre-charge for first segment
                    ↓
            Charge per segment processed

​
Important Notes

  • Webhook Configuration: Configure your webhook URL in user settings before using this API
  • No callback parameter needed: The system uses a unified asynchronous callback mechanism
  • Automatic segmentation: Every 5 seconds triggers a callback
  • Pre-charge mechanism: Balance is checked and pre-charged at start
  • Per-segment charging: Each processed segment is charged immediately
  • Auto-stop on insufficient balance: Stream automatically stops if balance is insufficient (status 402)
  • Concurrent stream limit: Each user has a maximum concurrent stream limit
  • Retry mechanism: Failed callbacks are automatically retried

​
Rate Limiting

  • Maximum concurrent streams: Each user can run N concurrent stream tasks (video + audio combined)
  • Capacity check: Returns status 16 if server capacity is reached
  • Balance check: Returns HTTP 402 if insufficient balance at start

Authorizations

​
Authorization
string
header
required

Body

application/json
​
url
string
required

Video stream URL (supports RTMP/RTSP)

Example:

"rtmp://example.com/live/stream"

​
enable_content_moderation
boolean
default:false

Enable content moderation

​
enable_logo_detection
boolean
default:false

Enable logo detection

​
fps
integer
default:1

Frames per second to process

Required range: x >= 1
​
max_logos
integer
default:5

Maximum number of logos to detect (1-50)

Required range: 1 <= x <= 50

Response

Stream started successfully

​
code
string
Example:

200

​
message
string
Example:

"success"

​
data
object