Mosaic API

https://docs.mosaic.so/
Admin
Mosaic API offers a powerful interface for automating professional-grade video editing with...
Tokens:26,794
Snippets:96
Trust Score:6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Dependencies (Bash)

Source: https://docs.mosaic.so/overview/video-upload

This command installs the necessary Python packages, 'moviepy' and 'requests', required for the Mosaic SO video upload functionality.

```bash
pip install moviepy requests
```

--------------------------------

### API Authentication and Usage Example

Source: https://docs.mosaic.so/overview/introduction

Demonstrates how to authenticate API requests using an API key and provides an example of calling the agent run endpoint.

```APIDOC
## API Authentication

Use an API key prefixed `mk_` for all API endpoints with the Authorization Bearer header.

### Request Example (cURL)

```bash
curl -H "Authorization: Bearer mk_your_key" \
     -H "Content-Type: application/json" \
     https://api.mosaic.so/agent/[agent_id]/run
```

## Base URL

```text
https://api.mosaic.so
```
```

--------------------------------

### Complete Workflow Example: Upload and Run Agent

Source: https://docs.mosaic.so/overview/agent-operations

A Python example demonstrating the full workflow: obtaining an upload URL, uploading a video file using policy fields, and then initiating an agent run. This illustrates the sequence of API calls required for processing videos with agents.

```python
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}")

```

--------------------------------

### YouTube Trigger Automation Setup (Python)

Source: https://context7.com/context7/mosaic_so/llms.txt

This Python script configures automatic video processing for YouTube channels using the Mosaic.so API. It demonstrates adding YouTube channels as triggers and then fetching the configured triggers to verify the setup. Requires the 'requests' library.

```python
import requests

API_KEY = "mk_your_api_key"
BASE_URL = "https://api.mosaic.so"
AGENT_ID = "{agent_id}"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Add YouTube channels to monitor
response = requests.post(
    f"{BASE_URL}/agent/{AGENT_ID}/triggers/add_youtube_channels",
    headers=headers,
    json={
        "youtube_channels": [
            "https://www.youtube.com/@yourchannel",
            "UCxxxxxxxxxxxxxx"
        ],
        "trigger_callback_url": "https://your-app.com/webhooks/youtube"
    }
)

# Check configured triggers
triggers_response = requests.get(
    f"{BASE_URL}/agent/{AGENT_ID}/triggers",
    headers=headers
)
trigger = triggers_response.json()

if trigger and trigger["type"] == "youtube":
    print(f"Monitoring {len(trigger['youtube_channels'])} channels")
    for channel in trigger["youtube_channels"]:
        print(f"  - {channel}")

```

--------------------------------

### Authenticate and Run Mosaic Agent (Bash)

Source: https://docs.mosaic.so/overview/introduction

Example demonstrating how to authenticate with the Mosaic API using an API key and trigger an agent to run on a video. Requires a valid API key and agent ID.

```bash
curl -H "Authorization: Bearer mk_your_key" \
     -H "Content-Type: application/json" \
     https://api.mosaic.so/agent/[agent_id]/run
```

--------------------------------

### Start Agent Run

Source: https://docs.mosaic.so/overview/webhooks

Initiates an agent run with provided video IDs and an optional callback URL for receiving status updates.

```APIDOC
## POST /agent/[agent_id]/run

### Description
Starts a new agent run. You can specify a list of video IDs to process and a callback URL where notifications about the run's status will be sent.

### Method
POST

### Endpoint
/agent/[agent_id]/run

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent to run.

#### Request Body
- **video_ids** (array of strings) - Required - A list of video IDs to be processed by the agent.
- **callback_url** (string) - Optional - The URL to which webhook notifications will be sent regarding the agent run status.
```

--------------------------------

### Start Agent Run with Callback URL

Source: https://docs.mosaic.so/overview/webhooks

Initiates an agent run by sending a POST request to the Mosaic.so API. It requires the agent ID, an API key for authorization, and a JSON payload containing video IDs and a callback URL for notifications.

```bash
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/abc123xyz"
  }'
```

--------------------------------

### Express.js Webhook Handler Example

Source: https://context7.com/context7/mosaic_so/llms.txt

An example Express.js route handler for processing incoming Mosaic webhooks. It verifies the signature, parses the payload using the defined TypeScript types, and logs information based on the webhook flag. Requires 'express' and a configured environment variable for the webhook secret.

```typescript
// Express webhook handler
import express from 'express';
const app = express();
app.use(express.json());

app.post('/webhooks/mosaic', (req, res) => {
  const signature = req.headers['x-mosaic-signature'] as string;
  const expectedSecret = process.env.MOSAIC_WEBHOOK_SECRET;

  if (expectedSecret && signature !== expectedSecret) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const payload = req.body as WebhookPayload;

  switch (payload.flag) {
    case 'RUN_STARTED':
      console.log(`Run ${payload.run_id} started`);
      break;
    case 'RUN_FINISHED':
      console.log(`Run ${payload.run_id} finished: ${payload.status}`);
      payload.outputs.forEach(output => {
        console.log(`Output: ${output.video_url}`);
      });
      break;
    case 'TEST':
      console.log('Test webhook received');
      break;
  }

  res.json({ received: true });
});
```

--------------------------------

### POST /videos/get_upload_url

Source: https://context7.com/context7/mosaic_so/llms.txt

Get a pre-signed URL and metadata for uploading a video.

```APIDOC
## POST /videos/get_upload_url

### Description
Retrieves a pre-signed URL and necessary metadata to upload a video file.

### Method
POST

### Endpoint
/videos/get_upload_url

### Parameters
#### Request Body
- **filename** (string) - Required - The name of the video file.
- **content_type** (string) - Required - The MIME type of the video file (e.g., "video/mp4").
- **file_size** (integer) - Required - The size of the video file in bytes.
- **width** (integer) - Required - The width of the video in pixels.
- **height** (integer) - Required - The height of the video in pixels.
- **duration_ms** (integer) - Required - The duration of the video in milliseconds.

### Request Example
```json
{
    "filename": "my-video.mp4",
    "content_type": "video/mp4",
    "file_size": 104857600,
    "width": 1920,
    "height": 1080,
    "duration_ms": 30000
}
```

### Response
#### Success Response (200)
- **upload_url** (string) - The pre-signed URL for uploading the video.
- **fields** (object) - Additional fields required for the upload.
- **video_id** (string) - The unique identifier for the video.

#### Response Example
```json
{
    "upload_url": "https://storage.googleapis.com/your-bucket/uploads/video.mp4?AWSAccessKeyId=...",
    "fields": {
        "key": "uploads/video.mp4",
        "AWSAccessKeyId": "...",
        "policy": "...",
        "signature": "..."
    },
    "video_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

--------------------------------

### API Key Validation Response (JSON)

Source: https://docs.mosaic.so/overview/introduction

Example JSON response from the `/whoami` endpoint, confirming a valid API key and providing details about the user account. This is used to test authentication.

```json
{
  "user_id": "123e4567-e89b-12d3-a456-789012345678",
  "email": "user@example.com",
  "is_admin": false,
  "api_key_id": "98765432-dcba-4321-abcd-987654321098",
  "created_at": "2024-01-15T08:00:00Z",
  "last_used_at": "2024-01-15T14:30:00Z"
}
```

--------------------------------

### Video Upload API

Source: https://docs.mosaic.so/overview/video-upload

This section details the process of uploading a video using the Mosaic.so API. It includes steps for getting an upload URL, uploading the video file with necessary fields, and finalizing the upload.

```APIDOC
## POST /videos/get_upload_url

### Description
Requests an upload URL and policy fields for uploading a video. Includes validation of video metadata.

### Method
POST

### Endpoint
/videos/get_upload_url

### Parameters
#### Query Parameters
None

#### Request Body
- **filename** (string) - Required - The name of the video file.
- **content_type** (string) - Required - The MIME type of the video file (e.g., "video/mp4").
- **file_size** (integer) - Required - The size of the video file in bytes.
- **width** (integer) - Required - The width of the video in pixels.
- **height** (integer) - Required - The height of the video in pixels.
- **duration_ms** (integer) - Required - The duration of the video in milliseconds.

### Request Example
```json
{
  "filename": "my-video.mp4",
  "content_type": "video/mp4",
  "file_size": 100000000,
  "width": 1920,
  "height": 1080,
  "duration_ms": 30000
}
```

### Response
#### Success Response (200)
- **video_id** (string) - The unique identifier for the video.
- **upload_url** (string) - The URL to which the video file should be uploaded.
- **fields** (object) - A map of fields to be included in the multipart form data for the upload.

#### Response Example
```json
{
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "upload_url": "https://storage.googleapis.com/...",
  "fields": {
    "key": "value",
    "another_key": "another_value"
  }
}
```

## POST /videos/finalize_upload

### Description
Finalizes the video upload, making the video available for processing. Validation is performed in Step 1, so this step is faster.

### Method
POST

### Endpoint
/videos/finalize_upload

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **video_id** (string) - Required - The video ID obtained from the `get_upload_url` step.

### Request Example
```json
{
  "video_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the finalization, typically "ok".

#### Response Example
```json
{
  "status": "ok"
}
```

### Response Codes
- 200 OK - Success - upload finalized
- 413 Payload Too Large - Video exceeds duration limit (90 minutes) or processing limits
- 400 Bad Request - Invalid video_id or upload not found
- 500 Internal Server Error - Server error during finalization
```

--------------------------------

### Upload Video to Mosaic SO (Python)

Source: https://docs.mosaic.so/overview/video-upload

This Python script demonstrates how to upload a video file to Mosaic SO using the provided API key. It includes error handling for the upload process. Ensure you have the 'moviepy' and 'requests' libraries installed.

```python
if __name__ == "__main__":
    # Install required dependency: pip install moviepy
    
    api_key = "mk_your_api_key_here"
    video_file = "path/to/your/video.mp4"
    
    try:
        video_id = upload_video_to_mosaic(api_key, video_file)
        if video_id:
            print(f"✅ Success! Use video_id '{video_id}' in your agent runs")
        else:
            print("❌ Upload failed")
    except Exception as e:
        print(f"❌ Error: {e}")
```

--------------------------------

### Video Upload - Request Upload URL

Source: https://context7.com/context7/mosaic_so/llms.txt

Get pre-signed URL and policy fields for uploading video to cloud storage.

```APIDOC
## POST /videos/get_upload_url

### Description
Get pre-signed URL and policy fields for uploading video to cloud storage.

### Method
POST

### Endpoint
/videos/get_upload_url

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **filename** (string) - Required - The name of the video file.
- **content_type** (string) - Required - The MIME type of the video file (e.g., `video/mp4`).
- **file_size** (integer) - Required - The size of the video file in bytes.
- **width** (integer) - Required - The width of the video in pixels.
- **height** (integer) - Required - The height of the video in pixels.
- **duration_ms** (integer) - Required - The duration of the video in milliseconds.

### Request Example
```json
{
  "filename": "my-video.mp4",
  "content_type": "video/mp4",
  "file_size": 104857600,
  "width": 1920,
  "height": 1080,
  "duration_ms": 30000
}
```

### Response
#### Success Response (200)
- **video_id** (string) - The unique identifier for the video.
- **upload_url** (string) - The pre-signed URL for uploading the video.
- **method** (string) - The HTTP method to use for the upload (e.g., `POST`).
- **fields** (object) - A map of fields required for the upload request.
  - **key** (string) - The object key in cloud storage.
  - **x-goog-date** (string) - The date for the signature.
  - **x-goog-credential** (string) - The credential for the signature.
  - **x-goog-algorithm** (string) - The signing algorithm.
  - **policy** (string) - The upload policy.
  - **x-goog-signature** (string) - The signature for the upload.

### Response Example
```json
{
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "upload_url": "https://storage.googleapis.com/mosaic-uploads/...",
  "method": "POST",
  "fields": {
    "key": "uploads/550e8400-e29b-41d4-a716-446655440000",
    "x-goog-date": "20240115T120000Z",
    "x-goog-credential": "...",
    "x-goog-algorithm": "GOOG4-RSA-SHA256",
    "policy": "...",
    "x-goog-signature": "..."
  }
}
```
```

--------------------------------

### Webhook Payload Examples for Mosaic.so

Source: https://docs.mosaic.so/overview/triggers

These JSON payloads represent the data sent by Mosaic.so webhooks. The 'RUN_STARTED' payload indicates the beginning of a processing run, while 'RUN_FINISHED' includes output details upon completion. The 'triggered_by' field is present for automated runs.

```json
{
  "flag": "RUN_STARTED",
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
  "status": "running",
  "inputs": [
    {
      "video_id": "youtube_dQw4w9WgXcQ",
      "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
    }
  ],
  "triggered_by": {
    "id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f",
    "type": "youtube",
    "youtube": {
      "id": "dQw4w9WgXcQ",
      "channel": "UCxxxxxxxxxxxxxx",
      "title": "Never Gonna Give You Up",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  }
}
```

```json
{
  "flag": "RUN_FINISHED",
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
  "status": "completed",
  "inputs": [
    {
      "video_id": "youtube_dQw4w9WgXcQ",
      "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
    }
  ],
  "outputs": [
    {
      "video_url": "https://storage.googleapis.com/mosaic-outputs/output.mp4",
      "thumbnail_url": "https://storage.googleapis.com/mosaic-thumbnails/thumb.jpg"
    }
  ],
  "triggered_by": {
    "id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f",
    "type": "youtube",
    "youtube": {
      "id": "dQw4w9WgXcQ",
      "channel": "UCxxxxxxxxxxxxxx",
      "title": "Never Gonna Give You Up",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  }
}
```

--------------------------------

### GET /agent/[agent_id]/triggers

Source: https://docs.mosaic.so/overview/triggers

Retrieves the YouTube trigger configuration for a specific agent. This includes the list of YouTube channels being monitored and the callback URL for notifications.

```APIDOC
## GET /agent/[agent_id]/triggers

### Description
Retrieve the YouTube trigger configured for an agent.

### Method
GET

### Endpoint
`/agent/[agent_id]/triggers`

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

### Request Example
```bash
curl -X GET "https://api.mosaic.so/agent/[agent_id]/triggers" \
  -H "Authorization: Bearer mk_your_api_key"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the trigger.
- **type** (string) - The type of the trigger (e.g., "youtube").
- **youtube_channels** (array of strings) - A list of YouTube channel URLs or IDs being monitored.
- **callback_url** (string) - The webhook URL to send notifications to when new content is detected.

Returns `null` if no trigger is configured.

#### Response Example
```json
{
  "id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f",
  "type": "youtube",
  "youtube_channels": [
    "https://www.youtube.com/channel/UCxxxxxx",
    "https://www.youtube.com/@channelname"
  ],
  "callback_url": "https://your-app.com/webhooks/trigger"
}
```
```

--------------------------------

### GET /agent_run/{run_id}

Source: https://context7.com/context7/mosaic_so/llms.txt

Poll the status of an ongoing agent run.

```APIDOC
## GET /agent_run/{run_id}

### Description
Retrieves the current status and results of an agent run.

### Method
GET

### Endpoint
/agent_run/{run_id}

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the agent run.

### Response
#### Success Response (200)
- **status** (string) - The current status of the run (e.g., "processing", "completed", "failed").
- **outputs** (array of objects) - A list of output video URLs if the run is completed.
  - **video_url** (string) - The URL of the processed video.

#### Response Example
```json
{
    "status": "completed",
    "outputs": [
        {
            "video_url": "https://storage.googleapis.com/your-bucket/processed/output.mp4"
        }
    ]
}
```
```

--------------------------------

### GET /agent/{agent_id}/triggers

Source: https://context7.com/context7/mosaic_so/llms.txt

Retrieve the configured triggers for a specific agent.

```APIDOC
## GET /agent/{agent_id}/triggers

### Description
Fetches the currently configured triggers for an agent, including YouTube channel monitoring settings.

### Method
GET

### Endpoint
/agent/[agent_id]/triggers

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the trigger configuration.
- **type** (string) - The type of trigger (e.g., "youtube").
- **youtube_channels** (array of strings) - List of monitored YouTube channels.
- **callback_url** (string) - The callback URL for notifications.

#### Response Example
```json
{
  "id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f",
  "type": "youtube",
  "youtube_channels": [
    "https://www.youtube.com/channel/UCxxxxxx",
    "https://www.youtube.com/@channelname"
  ],
  "callback_url": "https://your-app.com/webhooks/trigger"
}
```
```

--------------------------------

### Upload Video and Run Agent (Python)

Source: https://context7.com/context7/mosaic_so/llms.txt

This Python script demonstrates the process of uploading a video to Mosaic.so, running an agent on it, and polling for the agent's completion status. It requires the 'requests' library and assumes BASE_URL and headers are pre-configured.

```python
import requests
import time

# Assume BASE_URL and headers are defined, e.g.:
# BASE_URL = "https://api.mosaic.so"
# headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Step 1: Get upload URL with metadata
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",
                            "file_size": 104857600,
                            "width": 1920,
                            "height": 1080,
                            "duration_ms": 30000
                        })
upload_data = response.json()

# Step 2: Upload video with policy fields
with open("my-video.mp4", "rb") as video_file:
    files = {'file': ('my-video.mp4', video_file, 'video/mp4')}
    response = requests.post(upload_data["upload_url"],
                            data=upload_data['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

```

--------------------------------

### POST /agent/{agent_id}/run

Source: https://context7.com/context7/mosaic_so/llms.txt

Initiate an agent run with specified video IDs.

```APIDOC
## POST /agent/{agent_id}/run

### Description
Starts an agent process for one or more videos.

### Method
POST

### Endpoint
/agent/{agent_id}/run

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent to run.

#### Request Body
- **video_ids** (array of strings) - Required - A list of video IDs to process.

### Request Example
```json
{
    "video_ids": ["a1b2c3d4-e5f6-7890-1234-567890abcdef"]
}
```

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier for the agent run.

#### Response Example
```json
{
    "run_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef"
}
```
```

--------------------------------

### Validate API Key with /whoami (Bash)

Source: https://docs.mosaic.so/overview/introduction

This code snippet shows how to use the `/whoami` endpoint to verify the validity of your API key and retrieve associated user information. It's a crucial step for setting up authentication.

```bash
curl -X GET "https://api.mosaic.so/whoami" \
  -H "Authorization: Bearer mk_your_api_key"
```

--------------------------------

### GET /agent_run/[run_id]

Source: https://docs.mosaic.so/overview/agent-operations

Poll this endpoint to check the status of your agent run and retrieve outputs. This is useful for tracking the progress of agent executions.

```APIDOC
## GET /agent_run/[run_id]

### Description
Poll this endpoint to check the status of your agent run and retrieve outputs. This is useful for tracking the progress of agent executions.

### Method
GET

### Endpoint
/agent_run/{run_id}

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The ID of the agent run to retrieve status for.

#### Query Parameters
*None*

#### Request Body
*None*

### Request Example
*None*

### Response
#### Success Response (200)
- **agent_id** (string) - The ID of the agent that was run.
- **started_at** (string) - Timestamp when the agent run started.
- **status** (string) - The current status of the agent run (e.g., running, completed, failed).
- **inputs** (array of objects) - Details of the input videos.
  - **video_id** (string) - The ID of the input video.
  - **video_url** (string) - The URL of the input video.
  - **thumbnail_url** (string) - The URL of the input video's thumbnail.
- **outputs** (array of objects) - Details of the agent's outputs.
  - **video_url** (string) - The URL of the output video.
  - **thumbnail_url** (string) - The URL of the output video's thumbnail.
  - **completed_at** (string) - Timestamp when the output was completed.

#### Response Example
```json
{
  "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
- **running**: Agent is processing your videos
- **completed**: Processing finished successfully
- **failed**: An error occurred during processing
```

--------------------------------

### Complete Video Upload with Metadata Extraction

Source: https://context7.com/context7/mosaic_so/llms.txt

Demonstrates the full video upload workflow to Mosaic, including local metadata extraction and the 3-step upload process.

```APIDOC
## POST /videos/get_upload_url

### Description
Requests an upload URL for a video, providing metadata for validation.

### Method
POST

### Endpoint
https://api.mosaic.so/videos/get_upload_url

### Parameters
#### Request Body
- **filename** (string) - Required - The name of the video file.
- **content_type** (string) - Required - The MIME type of the video (e.g., 'video/mp4').
- **file_size** (integer) - Required - The size of the video file in bytes.
- **width** (integer) - Required - The width of the video in pixels.
- **height** (integer) - Required - The height of the video in pixels.
- **duration_ms** (integer) - Required - The duration of the video in milliseconds.

### Response
#### Success Response (200)
- **video_id** (string) - The unique identifier for the video.
- **upload_url** (string) - The URL to which the video file should be uploaded.

### Error Handling
- **413 Payload Too Large**: Indicates the file exceeds size or duration limits.
- **400 Bad Request**: Indicates invalid metadata provided.

## POST /videos/finalize_upload

### Description
Finalizes the upload process for a video after the file has been successfully uploaded.

### Method
POST

### Endpoint
https://api.mosaic.so/videos/finalize_upload

### Parameters
#### Request Body
- **video_id** (string) - Required - The unique identifier of the video to finalize.

### Response
#### Success Response (200)
Indicates successful finalization of the video upload.

### Error Handling
- **400 Bad Request**: If the video ID is invalid or the upload is not ready for finalization.
```

--------------------------------

### Run Agent via API (cURL)

Source: https://docs.mosaic.so/index

This cURL command demonstrates how to execute a pre-built video editing workflow (an Agent) using the Mosaic API. It requires your API key for authentication and the specific agent ID to run. The output will be a run ID to track the process.

```shell
curl -H "Authorization: Bearer mk_your_api_key"     https://api.mosaic.so/agent/[agent_id]/run
```

--------------------------------

### Authentication - Whoami Endpoint

Source: https://docs.mosaic.so/index

Test your API key with the `/whoami` endpoint to verify authentication.

```APIDOC
## GET /whoami

### Description
Tests the provided API key for authentication.

### Method
GET

### Endpoint
https://api.mosaic.so/whoami

### Parameters
#### Headers
- **Authorization** (string) - Required - API key prefixed with `mk_` (e.g., `Bearer mk_your_api_key`)

### Request Example
```bash
curl -H "Authorization: Bearer mk_your_api_key" \
     https://api.mosaic.so/whoami
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful authentication.

#### Response Example
```json
{
  "message": "Authenticated successfully"
}
```
```

--------------------------------

### Run Agent Workflow

Source: https://context7.com/context7/mosaic_so/llms.txt

Initiates an AI-powered video editing agent on uploaded videos and provides a callback URL for status updates.

```APIDOC
## POST /agent/[agent_id]/run

### Description
Executes a specified AI agent on one or more uploaded videos.

### Method
POST

### Endpoint
https://api.mosaic.so/agent/:agent_id/run

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent to run.

#### Request Body
- **video_ids** (array of strings) - Required - A list of video IDs to process.
- **callback_url** (string) - Optional - A URL to receive webhook notifications about the agent run status.

### Request Example
```json
{
  "video_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "callback_url": "https://your-app.com/webhooks/mosaic"
}
```

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier for this agent run.

### Response Example
```json
{
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d"
}
```
```

--------------------------------

### Webhook Signature Validation using Python Flask

Source: https://context7.com/context7/mosaic_so/llms.txt

Example Python Flask code to validate incoming webhook requests by checking the 'X-Mosaic-Signature' header against a secret stored in an environment variable. It processes 'RUN_STARTED' and 'RUN_FINISHED' flags.

```python
from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route('/webhooks/mosaic', methods=['POST'])
def handle_webhook():
    # Validate webhook signature
    webhook_signature = request.headers.get('X-Mosaic-Signature')
    expected_secret = os.environ.get('MOSAIC_WEBHOOK_SECRET')

    if expected_secret and webhook_signature != expected_secret:
        return jsonify({"error": "Invalid webhook signature"}), 401

    # Process webhook payload
    payload = request.json
    flag = payload.get('flag')

    if flag == 'RUN_STARTED':
        run_id = payload['run_id']
        print(f"Agent run {run_id} started")

    elif flag == 'RUN_FINISHED':
        run_id = payload['run_id']
        status = payload['status']
        outputs = payload.get('outputs', [])

        print(f"Agent run {run_id} finished with status: {status}")
        for output in outputs:
            print(f"  Output: {output['video_url']}")

    elif flag == 'TEST':
        print("Test webhook received")

    return jsonify({
        "received": true,
        "message": "Webhook processed successfully"
    }), 200

if __name__ == '__main__':
    app.run(port=5000)
```

--------------------------------

### Test API Key with /whoami (cURL)

Source: https://docs.mosaic.so/index

This cURL command verifies your API key by calling the `/whoami` endpoint on the Mosaic API. It's a simple way to confirm that your authentication is set up correctly before attempting more complex operations.

```shell
curl -H "Authorization: Bearer mk_your_api_key"     https://api.mosaic.so/whoami
```

--------------------------------

### Python: Complete Video Upload with Local Metadata Extraction to Mosaic

Source: https://context7.com/context7/mosaic_so/llms.txt

This Python script demonstrates the full video upload workflow to Mosaic. It includes extracting video metadata locally using moviepy, obtaining an upload URL from the Mosaic API, uploading the video file, and finalizing the upload process. Dependencies include the 'requests' and 'moviepy' libraries.

```python
import requests
import os
from moviepy.editor import VideoFileClip

def get_video_metadata(file_path: str) -> dict:
    """Extract metadata from video file."""
    with VideoFileClip(file_path) as clip:
        return {
            "width": clip.w,
            "height": clip.h,
            "duration_ms": int(clip.duration * 1000),
            "file_size": os.path.getsize(file_path)
        }

def upload_video_to_mosaic(api_key: str, file_path: str) -> str:
    """Upload a video file to Mosaic using the 3-step process."""

    headers = {"Authorization": f"Bearer {api_key}"}
    filename = os.path.basename(file_path)

    # Step 1: Extract metadata locally
    print("📊 Extracting video metadata...")
    metadata = get_video_metadata(file_path)
    print(f"   ✅ Metadata: {metadata['width']}x{metadata['height']}, "
          f"{metadata['duration_ms']/1000:.1f}s, {metadata['file_size']/(1024**2):.1f}MB")

    # Step 2: Get upload URL with validation
    print("📤 Getting upload URL...")
    response = requests.post(
        "https://api.mosaic.so/videos/get_upload_url",
        headers={**headers, "Content-Type": "application/json"},
        json={
            "filename": filename,
            "content_type": "video/mp4",
            "file_size": metadata["file_size"],
            "width": metadata["width"],
            "height": metadata["height"],
            "duration_ms": metadata["duration_ms"]
        }
    )

    if response.status_code == 413:
        raise Exception("File exceeds limits (>5GB or >90min)")
    elif response.status_code == 400:
        raise Exception("Invalid metadata")

    upload_data = response.json()
    video_id = upload_data["video_id"]
    print(f"   ✅ Got video_id: {video_id}")

    # Step 3: Upload video
    print("⬆️  Uploading video...")
    with open(file_path, "rb") as f:
        upload_response = requests.post(
            upload_data["upload_url"],
            headers={
                "x-goog-resumable": "start",
                "Content-Type": "video/mp4",
                "Content-Length": str(metadata["file_size"])
            },
            data=f
        )

    if upload_response.status_code not in [200, 201, 204]:
        raise Exception(f"Upload failed: {upload_response.status_code}")
    print("   ✅ Upload successful")

    # Step 4: Finalize upload
    print("✅ Finalizing upload...")
    finalize_response = requests.post(
        "https://api.mosaic.so/videos/finalize_upload",
        headers={**headers, "Content-Type": "application/json"},
        json={"video_id": video_id}
    )

    if finalize_response.status_code != 200:
        raise Exception("Finalization failed")

    print(f"🎉 Upload complete! Video ID: {video_id}")
    return video_id

# Usage
api_key = "mk_your_api_key"
video_id = upload_video_to_mosaic(api_key, "video.mp4")

```

--------------------------------

### Get Agent Run Status

Source: https://docs.mosaic.so/overview/agent-operations

Poll this endpoint to check the status of an agent run using its `run_id`. It returns details about the agent, processing status, inputs, and outputs. This is crucial for tracking the progress and retrieving results of agent workflows.

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

--------------------------------

### Configure Triggers with Webhook

Source: https://docs.mosaic.so/overview/webhooks

Sets up listeners for triggers, specifically for YouTube channels, and configures a webhook URL to receive notifications about automatic runs. This requires the agent ID, trigger type, channel IDs, and a trigger callback URL.

```bash
curl -X POST "https://api.mosaic.so/agent/[agent_id]/triggers/lowest_youtube_id/add_listeners" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "youtube_channels": ["UCxxxxxxxxxxxxxx"],
    "trigger_callback_url": "https://your-app.com/webhooks/triggers/def456uvw"
  }'
```

--------------------------------

### Poll Agent Run Status using Python

Source: https://docs.mosaic.so/overview/agent-operations

Periodically checks the status of an agent run by sending GET requests to the /agent_run/{run_id} endpoint until the status is 'completed' or 'failed'. Includes a delay between polls to avoid excessive API calls. Outputs video URLs upon successful completion.

```python
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
```

--------------------------------

### RUN_STARTED Webhook Payload Structure (JSON)

Source: https://docs.mosaic.so/overview/webhooks

This is the JSON structure for the RUN_STARTED webhook. It is sent when an agent run begins processing and includes details about the agent, the run, and the input videos. This payload is essential for tracking the initiation of agent processes.

```json
{
  "flag": "RUN_STARTED",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "run_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "running",
  "inputs": [
    {
      "video_url": "https://storage.googleapis.com/signed-url-example",
      "thumbnail_url": "https://storage.googleapis.com/signed-url-thumbnail"
    }
  ],
  "triggered_by": {
    "type": "youtube",
    "channel_id": "UC123456789",
    "video_id": "dQw4w9WgXcQ",
    "video_title": "Amazing Video Title",
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "triggered_at": "2024-01-15T10:30:00Z",
    "trigger_id": "aba7b810-9dad-11d1-80b4-00c04fd430c8"
  }
}
```

--------------------------------

### Whoami Endpoint - Validate API Key

Source: https://docs.mosaic.so/overview/introduction

The `/whoami` endpoint verifies the API key and returns information about the associated user.

```APIDOC
## GET /whoami

### Description

Verifies your API key is working correctly and retrieves information about the associated user account.

### Method

GET

### Endpoint

`/whoami`

### Parameters

No path or query parameters.

### Request Body

None

### Request Example (cURL)

```bash
curl -X GET "https://api.mosaic.so/whoami" \
  -H "Authorization: Bearer mk_your_api_key"
```

### Response

#### Success Response (200)

- **user_id** (string) - The unique identifier for the user.
- **email** (string) - The email address of the user.
- **is_admin** (boolean) - Indicates if the user is an administrator.
- **api_key_id** (string) - The unique identifier for the API key.
- **created_at** (string) - The timestamp when the API key was created (ISO 8601 format).
- **last_used_at** (string) - The timestamp when the API key was last used (ISO 8601 format).

#### Response Example

```json
{
  "user_id": "123e4567-e89b-12d3-a456-789012345678",
  "email": "user@example.com",
  "is_admin": false,
  "api_key_id": "98765432-dcba-4321-abcd-987654321098",
  "created_at": "2024-01-15T08:00:00Z",
  "last_used_at": "2024-01-15T14:30:00Z"
}
```

### Notes

This endpoint is crucial for validating API key setup and debugging authentication issues.
```
Tokens:
Raw