Memories.ai V2 API Skill#

Video intelligence API for transcripts, embeddings, AI analysis (VLM/ILM), and video operations.

Setup#

bash

# Set your API key
export MEMORIES_API_KEY="sk-mavi-your-key-here"

# Set your webhook URL for async callbacks (optional)
export MEMORIES_WEBHOOK_URL="https://your-server.com/webhook"

Quick Start#

python

from memories_sdk import MemoriesAI, Platform, ModelProvider

# Initialize client (uses MEMORIES_API_KEY and MEMORIES_WEBHOOK_URL env vars)
client = MemoriesAI()

# Or pass credentials directly
client = MemoriesAI(
    api_key="sk-mavi-...",
    webhook_url="https://your-server.com/webhook"  # for async callbacks
)

API Endpoints#

1. Social Video Transcripts (Sync)#

Get transcripts from YouTube, TikTok, Instagram, Twitter:

python

# Auto-detect platform
result = client.process_social_video("https://youtube.com/watch?v=abc123")

# Or specify platform
result = client.get_transcript(Platform.TIKTOK, "https://tiktok.com/@user/video/123")

2. MAI Transcripts (Async with Webhook)#

Deep video analysis with visual + audio transcription:

python

# Submit async task
task_id = client.submit_mai_transcript(
    Platform.YOUTUBE,
    "https://youtube.com/watch?v=abc123",
    callback_url="https://your-webhook.com/callback"  # optional
)

# Wait for result (polling)
status = client.wait_for_task(task_id, poll_interval=5, timeout=600)
print(status.data)

# Or use the workflow helper
result = client.process_video_mai_flow("https://youtube.com/watch?v=abc123", Platform.YOUTUBE)

3. Embeddings#

python

# Text embedding
embedding = client.get_text_embedding("Your text here")

# Image embedding
embedding = client.get_image_embedding("https://example.com/image.jpg")

# Video embedding
embedding = client.get_video_embedding("https://example.com/video.mp4")

4. AI Vision/Image Language Models#

Supported providers: gemini, nova, qwen, gpt

python

# Video analysis (VLM)
response = client.ai_vlm(
    ModelProvider.GEMINI,
    video_url="https://example.com/video.mp4",
    prompt="Describe what happens in this video"
)

# Image analysis (ILM)
response = client.ai_ilm(
    ModelProvider.GPT,
    image_url="https://example.com/image.jpg",
    prompt="What objects are in this image?"
)

5. Video Operations#

python

# Clip video
result = client.clip_video(video_url, start=10.0, end=30.0)

# Split video into segments
result = client.split_video(video_url, segments=[
    {"start": 0, "end": 10},
    {"start": 20, "end": 40}
])

# Extract frames at timestamps
result = client.extract_frames(video_url, timestamps=[1.0, 5.0, 10.0])

# Get video metadata
metadata = client.get_video_metadata(video_url)

# Upload local video
asset_url = client.upload_video("/path/to/video.mp4")

# Download video
client.download_video(video_url, "/path/to/save.mp4")

# Delete asset
client.delete_asset(asset_id)

6. Task Status#

python

# Check task status
status = client.get_task_status(task_id)
print(status.status)  # pending, processing, completed, failed
print(status.is_finished)
print(status.data)

# Wait for completion with timeout
status = client.wait_for_task(task_id, poll_interval=5, timeout=600)

Webhook Handling#

For async endpoints, results are delivered via webhook. Set up your own webhook server:

python

from memories_sdk import WebhookCallbackHandler

# In your FastAPI/Flask endpoint:
def webhook_handler(request_body):
    data = WebhookCallbackHandler.parse_callback(request_body)
    result = WebhookCallbackHandler.handle_status(data)
    return result

Note: You must provide your own webhook URL via MEMORIES_WEBHOOK_URL env var or webhook_url parameter.

Error Handling#

python

from memories_sdk import MemoriesError, APIError, AuthenticationError, TaskError

try:
    result = client.get_transcript(Platform.YOUTUBE, url)
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except APIError as e:
    print(f"API error {e.status_code}: {e.response}")
except TaskError as e:
    print(f"Task failed: {e}")
except MemoriesError as e:
    print(f"General error: {e}")

API Reference#

EndpointMethodDescription/{platform}/video/transcriptPOSTSync transcript/{platform}/video/mai/transcriptPOSTAsync MAI transcript/async/generate/video/transcriptPOSTAsync video transcript/async/generate/audio/transcriptPOSTAsync audio transcript/async/generate/speaker/transcriptPOSTSpeaker diarization/embeddings/textPOSTText embedding/embeddings/imagePOSTImage embedding/embeddings/videoPOSTVideo embedding/{provider}/vlmPOSTVideo language model/{provider}/ilmPOSTImage language model/video-clipPOSTExtract video clip/video-splitPOSTSplit video/video-editPOSTEdit video/extract-framesPOSTExtract frames/uploadPOSTUpload file/downloadPOSTDownload file/deletePOSTDelete asset/get-metadataPOSTGet video metadata/get-task-status/{task_id}GETCheck task status

Pricing (Approximate)#

• MAI Transcript: ~$0.10 per 40s video
• Simple Transcript: ~$0.02 per video
• Embeddings: Token-based pricing
• VLM/ILM: Per-request + token pricing

Links#

• API Docs: https://api-tools.memories.ai/llms.txt
• OpenAPI Spec: https://api-tools.memories.ai/api-reference/openapi.json