Mosaic API 技能

借助 Mosaic，你将成为一名 AI 视频编辑器。你可以创建并运行视频编辑工作流（“Agents”）、上传媒体素材、连接社交账号，并自动发布剪辑完成的视频。

API 密钥配置

在发起任何 API 调用前，你需要一个 Mosaic API 密钥（以 mk_ 开头）。

1. 首先检查运行环境。 如果 MOSAIC_API_KEY 已设置（例如通过 edit.mosaic.so 上的一键式配置），则直接使用该密钥。
2. 若环境中未设置密钥，请向用户索取。引导其访问 edit.mosaic.so/automations?tab=api，使用 OpenClaw 或 Claude Code 的一键式配置生成密钥。
3. 将密钥以 MOSAIC_API_KEY 形式保存至你的运行环境中，以便后续会话复用。
4. 使用请求头 Authorization: Bearer $MOSAIC_API_KEY 向 GET https://api.mosaic.so/whoami 发起验证请求。

HTTP 规约

• 基础 URL： https://api.mosaic.so
• 认证方式： Authorization: Bearer $MOSAIC_API_KEY
• 内容类型： Content-Type: application/json

工作流（Workflows）

每个工作流均有独立的操作指南。请根据当前任务查阅对应文档。

节点（Nodes，又称 Tiles）

Agents 是由若干节点（也称 “Tiles”）构成的有向图。每个节点执行一项编辑操作。如需查询可用节点及其参数定义，请调用：

GET /node_types          — 列出所有节点类型
GET /node_type/{node_type_id} — 获取指定节点类型的详细信息

各节点的 ID 及文档链接已整理于 nodes/ 目录下的参考文件中。当需要为 update_params 提供参数详情时，请查阅对应节点的文档文件。

编辑最佳实践

• 如需更紧凑的剪辑效果，建议将 Rough Cut 或 Clips 节点置于风格类节点（如 Style Nodes）之前。
• 建议将 Reframe 节点置于对布局敏感的节点（如 Captions、Cinematic Captions、Motion Graphics、Watermark）之前。
• 可通过将前序节点的 node_render_ids 传递给后续运行，实现编辑步骤的链式串联。

安全限制（Guardrails）

• update_params 中的键必须与 GET /agent/{agent_id} 响应中返回的 agent_node_id 值严格匹配。
• 非法参数覆盖将返回 400 错误。
• 对于字幕节点，caption_font_weight 必须为字符串类型（例如 "700"）。
• 对于 Motion Graphics 节点，请使用 style_video_url 和 only_generate_full_screen_graphics 参数。
• 若某次运行因积分不足被阻塞（即响应中含 needs_credits: true 或 needsCredits: true），请先按 workflows/credits-and-billing.md 中规定的计划校验与升级流程完成操作，再尝试恢复（resume）。
• 请勿使用 GET /credits/settings 进行读取操作；应使用 GET /credits 查询当前自动充值配置。
• 针对免费用户或未订阅付费计划的用户，请调用 GET /plan/list 获取可选方案列表，提示用户选择 plan_id，随后执行 POST /plan/upgrade。
• 升级成功后，务必询问用户是否启用自动充值；若用户确认，则通过 POST /credits/settings 配置其指定的阈值。

端点映射表

完整端点参考：references/docs-endpoints.md