Skip to main content

Overview

Agents are pre-built workflows that process your videos with AI-powered editing capabilities. Each agent is designed for specific tasks like generating captions, creating shorts, or enhancing audio.

Creating Agents

First, create an agent on app.mosaic.so. Once created, you can find the agent ID in the URL when viewing your agent.

POST /agent/[agent_id]/run

Execute an agent workflow on one or more uploaded videos.

Request

curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "callback_url": "https://your-app.com/webhooks/mosaic"
  }'

Parameters

FieldTypeRequiredDescription
video_idsstring[]Array of video IDs to process
callback_urlstringOptional webhook URL for status updates

Response

{
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d"
}
The run_id is used to track the progress of your agent run.

GET /agent_run/[run_id]

Poll this endpoint to check the status of your agent run and retrieve outputs.

Request

curl -X GET "https://api.mosaic.so/agent_run/[run_id]" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "started_at": "2025-01-10T14:30:00Z",
  "status": "completed",
  "inputs": [
    {
      "video_id": "550e8400-e29b-41d4-a716-446655440000",
      "video_url": "https://storage.googleapis.com/mosaic-inputs/...",
      "thumbnail_url": "https://storage.googleapis.com/mosaic-inputs/..."
    }
  ],
  "outputs": [
    {
      "video_url": "https://storage.googleapis.com/mosaic-outputs/...",
      "thumbnail_url": "https://storage.googleapis.com/mosaic-thumbnails/...",
      "completed_at": "2025-01-10T14:35:30Z"
    }
  ]
}

Status Values

StatusDescription
runningAgent is processing your videos
completedProcessing finished successfully
failedAn error occurred during processing

Webhook Callbacks

If you provide a callback_url when running an agent, Mosaic will send POST requests to notify you of status changes.

Webhook Payload

{
  "flag": "RUN_FINISHED",
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
  "status": "completed",
  "inputs": [
    {
      "video_url": "https://storage.googleapis.com/.../input.mp4",
      "thumbnail_url": "https://storage.googleapis.com/.../input-thumb.jpg"
    }
  ],
  "outputs": [
    {
      "video_url": "https://storage.googleapis.com/.../output.mp4",
      "thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg",
      "completed_at": "2025-01-10T14:35:30Z"
    }
  ]
}

Event Flags

FlagDescription
RUN_STARTEDSent when the agent begins processing
OUTPUT_FINISHEDSent when an individual output is completed
RUN_FINISHEDSent when processing completes (success or failure)
For agent runs triggered by external events (e.g., YouTube uploads), the webhook payload will include an additional triggered_by field. See Triggers for details.

Complete Example

Here’s a complete workflow from video upload to agent processing:
import requests
import time

API_KEY = "mk_your_api_key"
BASE_URL = "https://api.mosaic.so"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Step 1: Get upload URL and policy fields
response = requests.post(f"{BASE_URL}/videos/get_upload_url", 
                        headers={**headers, "Content-Type": "application/json"},
                        json={"filename": "my-video.mp4", "content_type": "video/mp4"})
upload_data = response.json()

# Step 2: Upload video with policy fields (multipart form)
with open("my-video.mp4", "rb") as video_file:
    # Build multipart form with policy fields first, then file
    files = {'file': ('my-video.mp4', video_file, 'video/mp4')}
    response = requests.post(upload_data["upload_url"], 
                            data=upload_data['fields'],  # Policy fields
                            files=files)
    
    if response.status_code != 204:
        raise Exception(f"Upload failed with status {response.status_code}")

# Step 3: Finalize upload
requests.post(f"{BASE_URL}/videos/finalize_upload", 
             headers={**headers, "Content-Type": "application/json"},
             json={"video_id": upload_data["video_id"]})

# Step 4: Run agent
agent_id = "{agent_id}"
run_response = requests.post(
    f"{BASE_URL}/agent/{agent_id}/run",
    headers={**headers, "Content-Type": "application/json"},
    json={"video_ids": [upload_data["video_id"]]}
)
run_id = run_response.json()["run_id"]

# Step 5: Poll for status
while True:
    status_response = requests.get(f"{BASE_URL}/agent_run/{run_id}", headers=headers)
    status_data = status_response.json()
    
    if status_data["status"] in ["completed", "failed"]:
        print(f"Agent run {status_data['status']}")
        if status_data["status"] == "completed":
            for output in status_data["outputs"]:
                print(f"Output video: {output['video_url']}")
        break
    
    time.sleep(5)  # Poll every 5 seconds

Best Practices

  1. Batch Processing: Process multiple videos in a single agent run for efficiency
  2. Webhooks vs Polling: Use webhooks for production systems to avoid unnecessary API calls
  3. Error Handling: Always handle the failed status and implement retry logic
  4. Agent Selection: Choose the right agent for your use case - visit the dashboard to explore available agents

Next Steps