Skill: kyle1373/mosaic-video-editor (version 1.3.0)

--- name: mosaic-video-editor description: AI-powered video editing via the Mosaic API. Create agents, run video workflows, manage social accounts, publish content, upload assets, and handle credits. Use when the user wants to edit videos, run agents, post to social media, or manage their Mosaic account programmatically. homepage: https://edit.mosaic.so metadata: {"openclaw":{"requires":{"env":["MOSAIC_API_KEY"]},"primaryEnv":"MOSAIC_API_KEY"}} --- # Mosaic API Skill With Mosaic you are an AI video editor. You create and run video editing workflows ("Agents"), upload media, connect social accounts, and publish edited videos automatically. ## API key setup Before any API call, you need a Mosaic API key (prefixed `mk_`). 1. **Check the environment first.** If `MOSAIC_API_KEY` is already set (e.g. via the one-click setup at [edit.mosaic.so](https://edit.mosaic.so)), use it directly. 2. If the key is not in the environment, ask the user for it. Direct them to [edit.mosaic.so/automations?tab=api](https://edit.mosaic.so/automations?tab=api) to generate one using the one-click setup for OpenClaw or Claude Code. 3. Store the key as `MOSAIC_API_KEY` in your environment for future sessions. 4. Validate with `GET https://api.mosaic.so/whoami` using header `Authorization: Bearer $MOSAIC_API_KEY`. ## HTTP conventions - **Base URL:** `https://api.mosaic.so` - **Auth:** `Authorization: Bearer $MOSAIC_API_KEY` - **Content:** `Content-Type: application/json` ## Workflows Each workflow has its own guide. Read the relevant file for the task at hand. | Task | Guide | |------|-------| | Create and manage agents | [workflows/managing-agents.md](workflows/managing-agents.md) | | Run an agent on video | [workflows/running-agents.md](workflows/running-agents.md) | | Upload video/audio/image assets | [workflows/uploading-assets.md](workflows/uploading-assets.md) | | Publish to social platforms | [workflows/social-publishing.md](workflows/social-publishing.md) | | Credits, billing, and auto top-ups | [workflows/credits-and-billing.md](workflows/credits-and-billing.md) | ## Nodes (tiles) Agents are graphs of **nodes** (also called "tiles"). Each node performs one editing action. To discover available nodes and their parameters, call: ``` GET /node_types — list all node types GET /node_type/{node_type_id} — get details for a specific node ``` Per-node reference files with IDs and docs links are in the [nodes/](nodes/) directory. Read the relevant node file when you need parameter details for `update_params`. ## Editing best practices - For tighter edits, place **Rough Cut** or **Clips** before style nodes. - Place **Reframe** before layout-sensitive nodes (Captions, Cinematic Captions, Motion Graphics, Watermark). - Chain edits by passing prior `node_render_ids` to subsequent runs. ## Guardrails - `update_params` keys must match `agent_node_id` values from `GET /agent/{agent_id}`. - Invalid overrides return `400`. - For captions, `caption_font_weight` must be string-typed (e.g. `"700"`). - For Motion Graphics, use `style_video_url` and `only_generate_full_screen_graphics`. - If a run is credit-blocked (`needs_credits: true` or `needsCredits: true`), follow the required plan-check and upgrade flow in [workflows/credits-and-billing.md](workflows/credits-and-billing.md) before attempting resume. - Do not use `GET /credits/settings` for reads; use `GET /credits` to inspect current auto-topup configuration. - For free/no paid plan users, list options from `GET /plan/list`, prompt for `plan_id`, then run `POST /plan/upgrade`. - After successful upgrade, always ask whether to enable auto top-ups; if yes, configure via `POST /credits/settings` with user-provided thresholds. ## Endpoint map Full endpoint reference: [references/docs-endpoints.md](references/docs-endpoints.md)

path: nodes/README.md
content: # Node Reference

Each file below describes one node type (tile) available in Mosaic agents. Files contain the node type ID and a link to full parameter docs.

To discover nodes at runtime, call:

```
GET /node_types              — list all available node types
GET /node_type/{node_type_id} — get full parameter schema for a node
```

When building `update_params` for a run, use the `agent_node_id` from `GET /agent/{agent_id}` (not the node type ID). The node type ID tells you *what kind* of node it is; the agent node ID tells you *which instance* in a specific agent graph.


path: nodes/ai-avatar.md
content: # AI Avatar

**Node type ID:** `b3b4c9e2-2a47-4fa9-8ce8-0c1fa1d7b6ef`

Generates a realistic AI-powered avatar to present or narrate video content. Ideal for creating professional talking-head videos without being on camera. You choose the avatar's appearance, voice, and delivery style, and Mosaic produces a video with natural lip sync and gestures.

To get the full list of configurable parameters, call `GET /node_type/b3b4c9e2-2a47-4fa9-8ce8-0c1fa1d7b6ef`.

[Full docs](https://docs.mosaic.so/tiles/ai-avatar)


path: nodes/ai-broll.md
content: # AI B-Roll

**Node type ID:** `2160392b-ebe8-4f3d-b81e-fd11bdbbeb77`

Automatically generates or sources relevant B-roll that matches what's being said in your video. Analyzes speech and topics, then generates short video shots for specific keywords, themes, or scenes. Especially useful for talking-head videos, interviews, podcasts, explainers, and educational content that benefit from visual support.

To get the full list of configurable parameters, call `GET /node_type/2160392b-ebe8-4f3d-b81e-fd11bdbbeb77`.

[Full docs](https://docs.mosaic.so/tiles/ai-broll)


path: nodes/ai-content-generation.md
content: # AI Content Generation

**Node type ID:** `d898f2b1-3151-4231-a4d4-dd4d5a020b05`

Automatically generates new video content from prompts, scripts, or topics using AI. Produces a complete video with visuals, narration, and structure -- no camera or footage required. You define the subject matter, style, and format; Mosaic generates scenes, creates visuals, and assembles the final output.

To get the full list of configurable parameters, call `GET /node_type/d898f2b1-3151-4231-a4d4-dd4d5a020b05`.

[Full docs](https://docs.mosaic.so/tiles/ai-content-generation)


path: nodes/ai-music.md
content: # AI Music

**Node type ID:** `3b281fb9-9eb2-40f6-b05b-4b6f909a3da9`

Generates custom AI-composed music that matches your video's mood, pacing, and style. Analyzes the video and produces a copyright-safe score. You can leave it fully automatic or guide it with prompts and settings.

To get the full list of configurable parameters, call `GET /node_type/3b281fb9-9eb2-40f6-b05b-4b6f909a3da9`.

[Full docs](https://docs.mosaic.so/tiles/ai-music)


path: nodes/ai-voiceover.md
content: # AI Voiceover

**Node type ID:** `9570c960-b32b-4e4d-8871-5775d886f7cb`

Generates narrated voiceover for your video using AI. Takes a written script (or auto-generates one), synthesizes a natural-sounding voice, and aligns it with your video. Useful for explainers, product demos, documentary-style narration, and storytelling.

To get the full list of configurable parameters, call `GET /node_type/9570c960-b32b-4e4d-8871-5775d886f7cb`.

[Full docs](https://docs.mosaic.so/tiles/ai-voiceover)


path: nodes/audio-enhance.md
content: # Audio Enhance

**Node type ID:** `425274c9-7735-4cf2-b7cb-46c6a7f0066a`

Automatically improves audio clarity and quality using AI. Reduces background noise, improves speech clarity, and balances audio levels. Especially useful for talking-head videos, podcasts, and interviews.

To get the full list of configurable parameters, call `GET /node_type/425274c9-7735-4cf2-b7cb-46c6a7f0066a`.

[Full docs](https://docs.mosaic.so/tiles/audio-enhance)


path: nodes/captions.md
content: # Captions

**Node type ID:** `cdccb204-168e-4aec-aa72-480b11e74324`

Add dynamic, stylized captions that match your video's tone and improve accessibility. Ideal for social platforms where sound-off viewing is common (TikTok, Reels, Shorts, LinkedIn). Listens to audio, transcribes speech, and overlays timed captions with your chosen styling.

To get the full list of configurable parameters, call `GET /node_type/cdccb204-168e-4aec-aa72-480b11e74324`.

Key parameters: `caption_style` (colored, scaling, karaoke), `base_color`, `highlight_color`, `stroke_color`, `stroke_width`, `caption_font`, `caption_font_weight` (string, e.g. `"700"`), `caption_vertical_position`, `caption_font_size`, `caption_min_words`, `caption_max_words`.

Place after Reframe if aspect ratio changes are needed.

[Full docs](https://docs.mosaic.so/tiles/captions)


path: nodes/cinematic-captions.md
content: # Cinematic Captions

**Node type ID:** `dfa94b02-6a18-4922-9613-636bd202d69d`

AI-powered cinematic captions with intelligent text placement. Uses Gemini to analyze your video and create captions that avoid covering important visual elements. Supports multiple fonts, animations, text backgrounds, and position control.

To get the full list of configurable parameters, call `GET /node_type/dfa94b02-6a18-4922-9613-636bd202d69d`.

Key parameters: `font1`, `font2`, `color_override` (null = AI picks colors), `text_bg_enabled`, `text_bg_color`, `text_bg_opacity`, `animation_style` (fade, pop, slide, typewriter, cinematic, highlight), `stroke_enabled`, `stroke_color`, `stroke_width`, `caption_position` (auto, or 3x3 grid: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right).

Place after Reframe if aspect ratio changes are needed.

[Full docs](https://docs.mosaic.so/tiles/cinematic-captions)


path: nodes/clips.md
content: # Clips

**Node type ID:** `bcc5cb04-76b7-48e9-a344-0e8a29c19be0`

Automatically extracts short, standalone clips from longer video. These clips are shareable moments for social platforms. Ideal for repurposing podcasts, interviews, webinars, or speaking content into short-form highlights.

To get the full list of configurable parameters, call `GET /node_type/bcc5cb04-76b7-48e9-a344-0e8a29c19be0`.

Place before style nodes for tighter edits.

[Full docs](https://docs.mosaic.so/tiles/clips)


path: nodes/color-correction.md
content: # Color Correction

**Node type ID:** `8254e1f8-dfea-42f9-90d8-aa91ec859bec`

Automatic color grading and correction for your video. Adjusts brightness, contrast, saturation, and color balance to give footage a polished, professional look.

To get the full list of configurable parameters, call `GET /node_type/8254e1f8-dfea-42f9-90d8-aa91ec859bec`.

[Full docs](https://docs.mosaic.so/tiles/color-correction)


path: nodes/intro.md
content: # Intro

**Node type ID:** `ef3f8d59-26be-4ea0-b655-9a08b10577cc`

Adds a branded intro sequence to the beginning of your video. Supports custom graphics, animations, and branding elements.

To get the full list of configurable parameters, call `GET /node_type/ef3f8d59-26be-4ea0-b655-9a08b10577cc`.

[Full docs](https://docs.mosaic.so/tiles/intro)


path: nodes/mirror.md
content: # Mirror

**Node type ID:** `71156aca-3e21-45b0-8960-099dba07c83a`

Flips video horizontally or vertically. Useful for correcting mirrored footage or creating visual effects.

To get the full list of configurable parameters, call `GET /node_type/71156aca-3e21-45b0-8960-099dba07c83a`.

[Full docs](https://docs.mosaic.so/tiles/mirror)


path: nodes/motion-graphics.md
content: # Motion Graphics

**Node type ID:** `19144346-8714-4a02-b19c-32c18bd1ad13`

Generates animated motion graphics overlays for your video. Useful for adding visual flair, data callouts, lower thirds, and animated text. Use `style_video_url` to provide a reference style and `only_generate_full_screen_graphics` to control layout. Do not use the deprecated `avoid_prompt` parameter.

To get the full list of configurable parameters, call `GET /node_type/19144346-8714-4a02-b19c-32c18bd1ad13`.

Place after Reframe if aspect ratio changes are needed.

[Full docs](https://docs.mosaic.so/tiles/motion-graphics)


path: nodes/outro.md
content: # Outro

**Node type ID:** `cf517f33-3f78-4d55-88c2-a7d8478f8ef9`

Adds a branded outro sequence to the end of your video. Supports custom graphics, calls to action, and branding elements.

To get the full list of configurable parameters, call `GET /node_type/cf517f33-3f78-4d55-88c2-a7d8478f8ef9`.

[Full docs](https://docs.mosaic.so/tiles/outro)


path: nodes/reframe.md
content: # Reframe

**Node type ID:** `0e3a90e4-173f-42fc-b7ef-0df6a062e26c`

Automatically converts your video into a different aspect ratio (9:16 for TikTok, 1:1 for Instagram, 16:9 for YouTube, etc.) while keeping the subject in view using intelligent face and object tracking. Essential for repurposing videos across platforms without manual cropping.

To get the full list of configurable parameters, call `GET /node_type/0e3a90e4-173f-42fc-b7ef-0df6a062e26c`.

Place BEFORE layout-sensitive nodes (Captions, Cinematic Captions, Motion Graphics, Watermark) so downstream composition respects the final framing.

[Full docs](https://docs.mosaic.so/tiles/reframe)


path: nodes/rough-cut.md
content: # Rough Cut

**Node type ID:** `e6098dd4-4a6e-470f-981e-2618c11eee21`

Automatically creates a rough cut from raw footage by keeping meaningful sections and removing filler, silence, or irrelevant content based on your creative intent. Useful for quickly condensing long-form footage into a cleaner baseline edit.

To get the full list of configurable parameters, call `GET /node_type/e6098dd4-4a6e-470f-981e-2618c11eee21`.

Place before style-heavy nodes for tighter edits.

[Full docs](https://docs.mosaic.so/tiles/rough-cut)


path: nodes/silence-removal.md
content: # Silence Removal

**Node type ID:** `a22d0b93-2bbf-479d-8efd-d446163982e8`

Automatically removes awkward pauses, long gaps, and dead air from your video to make pacing tighter and more engaging. Analyzes audio to detect silence and trims it out. Especially useful for podcasts, commentary, educational content, and talking-head videos.

To get the full list of configurable parameters, call `GET /node_type/a22d0b93-2bbf-479d-8efd-d446163982e8`.

[Full docs](https://docs.mosaic.so/tiles/silence-removal)


path: nodes/video-input.md
content: # Video Input

**Node type ID:** `9451e6ff-ac7f-4317-9055-a2f35f641b29`

The input node that accepts video into an agent graph. This is typically the first node in a workflow. Videos are provided via `video_urls`, `video_ids` (from the Uploads API), or `node_render_ids` (from prior run outputs) in the run payload.

To get the full list of configurable parameters, call `GET /node_type/9451e6ff-ac7f-4317-9055-a2f35f641b29`.

[Full docs](https://docs.mosaic.so/tiles/input-tiles)


path: nodes/voice.md
content: # Voice

**Node type ID:** `14abd0c1-402c-40b8-8ec8-defd951efe01`

Modifies spoken audio using AI -- dubbing into different languages, swapping specific words, and generating lip-synced speech. Valuable for repurposing videos globally, correcting misspoken words, or adjusting terminology without re-recording.

To get the full list of configurable parameters, call `GET /node_type/14abd0c1-402c-40b8-8ec8-defd951efe01`.

[Full docs](https://docs.mosaic.so/tiles/voice)


path: nodes/watermark.md
content: # Watermark

**Node type ID:** `6808af58-2d9a-4e3b-aacb-2d9c143b7729`

Overlays a watermark image on your video. Supports positioning, sizing, and opacity control for brand logos or attribution marks.

To get the full list of configurable parameters, call `GET /node_type/6808af58-2d9a-4e3b-aacb-2d9c143b7729`.

Place after Reframe if aspect ratio changes are needed.

[Full docs](https://docs.mosaic.so/tiles/watermark)


path: references/docs-endpoints.md
content: # Mosaic API Endpoint Map

Canonical docs:
- [Docs home](https://docs.mosaic.so)
- [API reference index](https://docs.mosaic.so/api/introduction)

## Agents

- [`POST /agent/create`](https://docs.mosaic.so/api/agents/post-agent-create)
- [`POST /agent/{agent_id}/update`](https://docs.mosaic.so/api/agents/post-agent-update)
- [`POST /agent/{agent_id}/delete`](https://docs.mosaic.so/api/agents/post-agent-delete)
- [`POST /agent/{agent_id}/duplicate`](https://docs.mosaic.so/api/agents/post-agent-duplicate)
- [`GET /agents`](https://docs.mosaic.so/api/agents/get-agents)
- [`GET /agent/{agent_id}`](https://docs.mosaic.so/api/agents/get-agent)

## Runs

- [`GET /agent/{agent_id}/runs`](https://docs.mosaic.so/api/agent-runs/get-agent-runs)
- [`GET /agent_runs`](https://docs.mosaic.so/api/agent-runs/get-all-agent-runs)
- [`GET /trigger/{trigger_id}/runs`](https://docs.mosaic.so/api/agent-runs/get-trigger-runs)
- [`POST /agent/{agent_id}/run`](https://docs.mosaic.so/api/agent-runs/post-agent-run)
- [`GET /agent_run/{run_id}`](https://docs.mosaic.so/api/agent-runs/get-agent-run)
- [`GET /agent_run/{run_id}/nodes`](https://docs.mosaic.so/api/agent-runs/get-agent-run-nodes)
- [`POST /agent_run/{run_id}/resume`](https://docs.mosaic.so/api/agent-runs/post-agent-run-resume)
- [`POST /agent_run/{run_id}/cancel`](https://docs.mosaic.so/api/agent-runs/post-agent-run-cancel)

## Node discovery

- [`GET /node_types`](https://docs.mosaic.so/api/agent-nodes/get-agent-nodes)
- [`GET /node_type/{node_type_id}`](https://docs.mosaic.so/api/node-types/get-node-type)
- [`GET /agent_nodes/{agent_node_id}`](https://docs.mosaic.so/api/agent-nodes/get-agent-node)

## Triggers

- [`GET /agent/{agent_id}/triggers`](https://docs.mosaic.so/api/triggers/get-agent-triggers)
- [`POST /agent/{agent_id}/triggers/add_youtube_channels`](https://docs.mosaic.so/api/triggers/post-add-youtube-channels)
- [`POST /agent/{agent_id}/triggers/remove_youtube_channels`](https://docs.mosaic.so/api/triggers/post-remove-youtube-channels)

## Credits & billing

- [`GET /credits`](https://docs.mosaic.so/api/credits/get-credits)
- [`GET /credits/usage`](https://docs.mosaic.so/api/credits/get-credits-usage)
- [`POST /credits/settings`](https://docs.mosaic.so/api/credits/post-credits-settings)
- [`GET /plan`](https://docs.mosaic.so/api/plan/get-plan)
- [`GET /plan/list`](https://docs.mosaic.so/api/plan/get-plan-list)
- [`POST /plan/upgrade`](https://docs.mosaic.so/api/plan/post-plan-upgrade)

## Social publishing

- [`POST /social/{platform}/connect`](https://docs.mosaic.so/api/social/post-social-platform-connect)
- [`GET /social/{platform}/status`](https://docs.mosaic.so/api/social/get-social-platform-status)
- [`DELETE /social/{platform}/remove`](https://docs.mosaic.so/api/social/delete-social-platform-remove)
- [`POST /social/post`](https://docs.mosaic.so/api/social/post-social-post)
- [`GET /social/post/{post_id}`](https://docs.mosaic.so/api/social/get-social-post)
- [`GET /social/post/track/{tracking_id}`](https://docs.mosaic.so/api/social/get-social-post-track)
- [`PATCH /social/post/{post_id}`](https://docs.mosaic.so/api/social/patch-social-post)
- [`DELETE /social/post/{post_id}`](https://docs.mosaic.so/api/social/delete-social-post)

## Asset management

- [`POST /uploads/video/get_upload_url`](https://docs.mosaic.so/api/asset-management/post-uploads-video-get-upload-url)
- [`POST /uploads/video/finalize_upload`](https://docs.mosaic.so/api/asset-management/post-uploads-video-finalize-upload)
- [`POST /uploads/audio/get_upload_url`](https://docs.mosaic.so/api/asset-management/post-uploads-audio-get-upload-url)
- [`POST /uploads/audio/finalize_upload`](https://docs.mosaic.so/api/asset-management/post-uploads-audio-finalize-upload)
- [`POST /uploads/image/get_upload_url`](https://docs.mosaic.so/api/asset-management/post-uploads-image-get-upload-url)
- [`POST /uploads/image/finalize_upload`](https://docs.mosaic.so/api/asset-management/post-uploads-image-finalize-upload)
- [`POST /uploads/get_view_url`](https://docs.mosaic.so/api/asset-management/post-uploads-get-view-url)

## Webhooks

- [Webhook events](https://docs.mosaic.so/api/webhooks/events)


path: workflows/credits-and-billing.md
content: # Credits & Billing

## Read credit state (balance + auto top-up)

```
GET /credits
```

This endpoint returns balance, active plan metadata, billing cycle dates, and current `auto_topup` settings in one response.

[Docs](https://docs.mosaic.so/api/credits/get-credits)

## Update auto top-up settings

Use:

```bash
POST /credits/settings
```

Example body:

```json
{
  "auto_topup": {
    "enabled": true,
    "threshold": 1000,
    "quantity": 5000
  }
}
```

When credit balance drops below `threshold`, `quantity` credits are purchased automatically at your plan's rate.

Notes:
- Requires an eligible paid plan (Creator/Professional family); free plans receive `403`.
- To read current top-up values, use `GET /credits` (not `GET /credits/settings`).

[Docs](https://docs.mosaic.so/api/credits/post-credits-settings)

## View current plan

```
GET /plan
```

[Docs](https://docs.mosaic.so/api/plan/get-plan)

## List available plans (for upgrade UX)

```
GET /plan/list
```

Typical plan IDs: `creator`, `creator_annual`, `professional`, `professional_annual`, `pro`.

[Docs](https://docs.mosaic.so/api/plan/get-plan-list)

## Upgrade plan

```json
POST /plan/upgrade
{ "plan_id": "professional" }
```

Possible responses:
- Immediate change (`requires_checkout: false`)
- Checkout required (`requires_checkout: true`, with `checkout_url`)

[Docs](https://docs.mosaic.so/api/plan/post-plan-upgrade)

## Required flow for credit-blocked runs

When a run or node is marked as needing credits (`needs_credits: true` or `needsCredits: true`), do this in order:

1. **Check plan first:** `GET /plan`
2. **If user is on free/no paid plan:**
   - Tell the user a paid plan is required to continue the run.
   - Call `GET /plan/list`.
   - Present available plans (`id`, `billing`, `price_usd`, `credits_per_month`, `top_up_rate_per_100_credits_usd`).
   - Ask which `plan_id` to upgrade to.
   - Call `POST /plan/upgrade` with that `plan_id`.
3. **If upgrade requires checkout (`requires_checkout: true`):**
   - Share the `checkout_url` with the user.
   - Wait for confirmation that checkout is complete.
   - Re-check with `GET /plan` before proceeding.
4. **After upgrade succeeds:** ask whether to enable auto top-ups.
5. **If yes:** collect `threshold` and `quantity` and call `POST /credits/settings`.
6. **Then resume blocked work:** `POST /agent_run/{run_id}/resume`.


path: workflows/managing-agents.md
content: # Managing Agents

Agents are reusable video editing workflows (graphs of nodes/tiles).

## List agents

```
GET /agents
```

Returns all agents in your organization. [Docs](https://docs.mosaic.so/api/agents/get-agents)

## Get agent details

```
GET /agent/{agent_id}
```

Returns the full node graph. Use the `agent_node_id` values from the response to build `update_params` and `video_inputs`. [Docs](https://docs.mosaic.so/api/agents/get-agent)

## Create an agent

```
POST /agent/create
```

[Docs](https://docs.mosaic.so/api/agents/post-agent-create)

## Update an agent

```
POST /agent/{agent_id}/update
```

[Docs](https://docs.mosaic.so/api/agents/post-agent-update)

## Duplicate an agent

```
POST /agent/{agent_id}/duplicate
```

Creates a copy of an existing agent. [Docs](https://docs.mosaic.so/api/agents/post-agent-duplicate)

## Delete an agent

```
POST /agent/{agent_id}/delete
```

[Docs](https://docs.mosaic.so/api/agents/post-agent-delete)


path: workflows/running-agents.md
content: # Running Agents

## Procedure

1. **Get agent graph:** `GET /agent/{agent_id}` to find `agent_node_id` values.
2. **Start run:** `POST /agent/{agent_id}/run` with video input payload.
3. **Poll status:** `GET /agent_run/{run_id}` until `status` is `completed` or `failed`.
4. **Inspect nodes:** `GET /agent_run/{run_id}/nodes` for per-node status on failure.
5. **Credit-block handling:** if run/node has `needs_credits: true` (or `needsCredits: true`), follow the required flow in [credits-and-billing.md](credits-and-billing.md) before resuming.
6. **Resume:** `POST /agent_run/{run_id}/resume` to retry failed/blocked nodes.
7. **Cancel:** `POST /agent_run/{run_id}/cancel` to abort a running agent.

## Run payload templates

### Single-input (URL)

```json
{
  "video_urls": ["https://example.com/video.mp4"],
  "callback_url": "https://your-webhook.com/callback"
}
```

### Single-input (uploaded asset)

```json
{
  "video_ids": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"]
}
```

`video_ids` come from the Uploads API — see [uploading-assets.md](uploading-assets.md).

### Single-input (chain from prior run)

```json
{
  "node_render_ids": ["7ba7b810-9dad-11d1-80b4-00c04fd430c8"]
}
```

`node_render_ids` come from prior run outputs (`GET /agent_run/{run_id}` → `outputs[].id`).

### Multi-input (canonical)

Use when the agent has multiple input nodes:

```json
{
  "video_inputs": [
    { "agent_node_id": "NODE_ID_1", "video_urls": ["https://..."] },
    { "agent_node_id": "NODE_ID_2", "node_render_ids": ["PRIOR_OUTPUT_ID"] }
  ],
  "callback_url": "https://your-webhook.com/callback"
}
```

## Overriding node parameters

Pass `update_params` to override node settings at run time:

```json
{
  "video_urls": ["https://..."],
  "update_params": {
    "AGENT_NODE_ID": {
      "param_key": "value"
    }
  }
}
```

Keys in `update_params` must be `agent_node_id` values from `GET /agent/{agent_id}`. Invalid keys return `400`.

## Credit-blocked runs (`needs_credits`)

If `GET /agent_run/{run_id}` or `GET /agent_run/{run_id}/nodes` indicates the run is credit-blocked:

1. Check current plan with `GET /plan`.
2. If user is free/no paid plan, list options via `GET /plan/list` and run `POST /plan/upgrade`.
3. Optionally enable auto top-ups via `POST /credits/settings`.
4. Resume with `POST /agent_run/{run_id}/resume`.

For the full required sequence and user-prompt behavior, use [credits-and-billing.md](credits-and-billing.md).

## Listing runs

- By agent: `GET /agent/{agent_id}/runs` — [Docs](https://docs.mosaic.so/api/agent-runs/get-agent-runs)
- All runs: `GET /agent_runs` — [Docs](https://docs.mosaic.so/api/agent-runs/get-all-agent-runs)
- By trigger: `GET /trigger/{trigger_id}/runs` — [Docs](https://docs.mosaic.so/api/agent-runs/get-trigger-runs)

## Docs

- [Run Agent](https://docs.mosaic.so/api/agent-runs/post-agent-run)
- [Get Run](https://docs.mosaic.so/api/agent-runs/get-agent-run)
- [Get Run Nodes](https://docs.mosaic.so/api/agent-runs/get-agent-run-nodes)
- [Resume Run](https://docs.mosaic.so/api/agent-runs/post-agent-run-resume)
- [Cancel Run](https://docs.mosaic.so/api/agent-runs/post-agent-run-cancel)


path: workflows/social-publishing.md
content: # Social Publishing

Connect social accounts and publish edited videos directly from the API.

## Procedure

1. **Connect account:** `POST /social/{platform}/connect`
2. **Run agent** and wait for `outputs[].video_url` in the completed run.
3. **Publish:** `POST /social/post` with `media_urls` pointing to the output.
4. **Track:** Poll `GET /social/post/{post_id}` or `GET /social/post/track/{tracking_id}`.

## Supported platforms

`youtube`, `tiktok`, `instagram`, `facebook`, `linkedin`, `x`

## Connect a platform

```
POST /social/{platform}/connect
```

[Docs](https://docs.mosaic.so/api/social/post-social-platform-connect)

## Check connection status

```
GET /social/{platform}/status
```

[Docs](https://docs.mosaic.so/api/social/get-social-platform-status)

## Disconnect a platform

```
DELETE /social/{platform}/remove
```

[Docs](https://docs.mosaic.so/api/social/delete-social-platform-remove)

## Create a post

```json
POST /social/post
{
  "platform": "youtube",
  "media_urls": ["https://...output_video_url..."],
  "title": "My Edited Video",
  "description": "Published via Mosaic API"
}
```

[Docs](https://docs.mosaic.so/api/social/post-social-post)

## Track post status

- `GET /social/post/{post_id}` — [Docs](https://docs.mosaic.so/api/social/get-social-post)
- `GET /social/post/track/{tracking_id}` — [Docs](https://docs.mosaic.so/api/social/get-social-post-track)

## Update / delete a post

- `PATCH /social/post/{post_id}` — [Docs](https://docs.mosaic.so/api/social/patch-social-post)
- `DELETE /social/post/{post_id}` — [Docs](https://docs.mosaic.so/api/social/delete-social-post)


path: workflows/uploading-assets.md
content: # Uploading Assets

Upload video, audio, or image files to use as inputs in agent runs.

## Procedure

1. **Get upload URL:** `POST /uploads/{type}/get_upload_url` (type: `video`, `audio`, `image`)
2. **Upload file:** PUT the file to the returned signed URL.
3. **Finalize:** `POST /uploads/{type}/finalize_upload` with the upload ID.
4. **Use in runs:** Pass the resulting asset UUID as `video_ids` in your run payload.

## Get a view URL

To get a temporary signed URL for an existing asset:

```
POST /uploads/get_view_url
```

## Docs

- [Upload flow overview](https://docs.mosaic.so/api/asset-management/upload-flow)
- [Video upload URL](https://docs.mosaic.so/api/asset-management/post-uploads-video-get-upload-url)
- [Finalize video](https://docs.mosaic.so/api/asset-management/post-uploads-video-finalize-upload)
- [Audio upload URL](https://docs.mosaic.so/api/asset-management/post-uploads-audio-get-upload-url)
- [Finalize audio](https://docs.mosaic.so/api/asset-management/post-uploads-audio-finalize-upload)
- [Image upload URL](https://docs.mosaic.so/api/asset-management/post-uploads-image-get-upload-url)
- [Finalize image](https://docs.mosaic.so/api/asset-management/post-uploads-image-finalize-upload)
- [Get view URL](https://docs.mosaic.so/api/asset-management/post-uploads-get-view-url)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)