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), 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 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.

TaskGuideCreate and manage agentsworkflows/managing-agents.mdRun an agent on videoworkflows/running-agents.mdUpload video/audio/image assetsworkflows/uploading-assets.mdPublish to social platformsworkflows/social-publishing.mdCredits, billing, and auto top-upsworkflows/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:

text

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/ 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 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