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 edit.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. Supports standard video-input workflows and AI-only workflows (AI Content Generation or AI Avatar).

​
Standard Workflows

For workflows starting with a Video Input node, you must provide video URLs. The backend will automatically detect the URL type, download the video, and run the workflow. 
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_urls": [
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'

​
AI-Only Workflows

For workflows starting with AI Content Generation or AI Avatar nodes (and no Video Input node), no video inputs should be provided. These agents generate video content based on the parameters configured in the agent. 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-webhook.com/callback",
    "update_params": {
      "NODE_ID": {
        "prompt": "A futuristic city in the style of cyberpunk"
      }
    }
  }'

​
Parameters

FieldTypeRequiredDescription
video_urlsstring[]Array of video URLs to process. Required if the agent has a video input node. Supports YouTube URLs and signed URLs (HTTP/HTTPS).
callback_urlstringOptional webhook URL for status updates
update_paramsobjectOptional parameters to override node parameters in the agent workflow

​
Video URL Requirements & Limits

The video_urls field supports two types of URLs: YouTube URLs:
  • Supports standard YouTube video URLs (e.g., https://www.youtube.com/watch?v=VIDEO_ID)
  • Maximum duration: 1 hour per video
  • The system automatically validates the video exists and checks duration before processing
Signed URLs (HTTP/HTTPS):
  • Must be HTTP or HTTPS URLs pointing to video files
  • Maximum file size: 5 GB per video
  • Maximum duration: 3 hours per video

​
Modifying Node Parameters

You can override specific parameters for any node in your agent workflow using the update_params field. This allows you to dynamically change behavior (like clip duration, prompt text, or number of clips) at runtime. To find the correct parameters:
  1. Open your agent in the Mosaic Dashboard
  2. Click the settings icon on the node you want to modify
  3. Click “Learn more about [Node Name]” to expand the dev details
  4. Click Copy parameters to get the JSON structure
Dev Mode Example The copied JSON will look like this, where the key is the Node ID (UUID) and the value object contains the parameters you can override: 
{
  "bf750792-a2e9-48c2-9d39-24f892772f6a": {
    "num_clips": 10,
    "target_duration": 60
  }
}
Pass this entire object as the update_params value in your API request.

​
Uploading Media for Node Parameters

Some nodes accept images, audio, or videos as parameters. To set these programmatically, use the Uploads API to upload your files and get their UUIDs: 
{
  "video_urls": ["https://youtube.com/watch?v=..."],
  "update_params": {
    "AUDIO_NODE_ID": {
      "audio_id": "your-uploaded-audio-uuid"
    },
    "IMAGE_NODE_ID": {
      "image_id": "your-uploaded-image-uuid"
    }
  }
}
See the Uploads documentation for the complete upload flow.

​
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",
  "status_message": null,
  "node_status_counts": {
    "completed": 10,
    "in_progress": 0,
    "failed": 0
  },
  "inputs": [
    {
      "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
partial_completeSome outputs finished successfully, but others failed
failedThe entire run failed, no outputs generated
cancelledThe run was cancelled by the user

​
POST /agent_run/[run_id]/cancel

Cancel an ongoing agent run. This stops all running tasks and prevents downstream nodes from starting.

​
Request

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

​
Response

{
  "success": true,
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
  "tasks_cancelled": 2,
  "nodes_reset": 3,
  "message": "Agent run cancelled successfully"
}

​
Webhook Callbacks

If you provide a callback_url when running an agent, Mosaic will send POST requests to notify you of status changes. See the Webhooks section for complete webhook documentation.

​
Next Steps