Agent · 能力开放

同一套生成能力，Agent 通过 REST（或未来的 MCP）一句话调用；与人类画布入口共用任务引擎与计费账本。

调用示例

POST /api/v1/agent/skill/generate_video
Authorization: Bearer sk_demo_guozhangmen_aigc
Idempotency-Key: agent-op-001

{
  "prompt": "霓虹街头女子撑伞回眸，电影感",
  "model": "seedance-2.5",
  "duration": 8,
  "ratio": "9:16"
}

→ { "task_id": "task_0001", "status": "queued", "estimated_credits": 52 }

结果获取三选一：GET /api/v1/agent/skill/:name/tasks/:id 轮询 · 提交时带 callback_url 走 Webhook 回调 · MCP 通道在 tool 内聚合成同步返回。

会话上下文（多轮产物引用）

Webhook 回调投递

提交任务时带 callback_url，终态即 POST 结果（HMAC-SHA256 签名头 X-Signature），失败按 1s / 5s / 25s 退避重试最多 3 次。

暂无投递记录。

Skill 列表

generate_image异步

根据提示词生成图片（文生图 / 图生图）

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "画面描述"
    },
    "model": {
      "type": "string",
      "enum": [
        "gzm-image-1"
      ]
    },
    "ratio": {
      "type": "string",
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ]
    },
    "first_frame": {
      "type": "string",
      "description": "参考图 URL / asset id"
    }
  },
  "required": [
    "prompt"
  ]
}

generate_video异步

根据提示词与参考图生成视频片段

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "视频内容描述"
    },
    "model": {
      "type": "string",
      "enum": [
        "kling3",
        "seedance-2.5",
        "minimax-h3"
      ]
    },
    "first_frame": {
      "type": "string",
      "description": "参考图 URL / asset id"
    },
    "duration": {
      "type": "integer",
      "minimum": 5,
      "maximum": 30
    },
    "ratio": {
      "type": "string",
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ]
    }
  },
  "required": [
    "prompt"
  ]
}

generate_audio异步

文本转语音 / 配乐生成

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "配音文本"
    },
    "voice": {
      "type": "string",
      "enum": [
        "female_warm",
        "male_deep",
        "girl_lively"
      ]
    }
  },
  "required": [
    "prompt"
  ]
}

script_storyboard同步

由一句话创意生成剧本与分镜列表

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "一句话创意"
    },
    "shots": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "prompt"
  ]
}

storyboard_team同步

分镜创作团队（三角色编排）：编剧按剧情节拍出文字分镜 → 审阅按连续性清单核查 → 导演整合终稿并标注待确认项。产出可执行的分镜 JSON，不包含媒体生成

{
  "type": "object",
  "properties": {
    "story": {
      "type": "string",
      "description": "故事/剧情（可含角色与场景设定）"
    },
    "duration": {
      "type": "integer",
      "description": "目标时长（秒）"
    },
    "constraints": {
      "type": "string",
      "description": "额外约束：风格、画幅、角色设定等"
    }
  },
  "required": [
    "story"
  ]
}

compose_video同步

把多段视频剪辑成片：片段按序拼接（可选淡入淡出转场）+ 可选配音/配乐混音。clips 支持上游节点引用（如 v1.task_id，多段逗号分隔）/ 任务号 / URL / /files/ 路径；本地 ffmpeg 执行，不消耗积分；上游生成任务是异步的，本 Skill 会等它们完成再剪辑

{
  "type": "object",
  "properties": {
    "clips": {
      "type": "string",
      "description": "片段列表（逗号或换行分隔），顺序即成片顺序。每项可为上游引用 key、task_ 任务号、http(s) URL 或 /files/ 路径"
    },
    "audio": {
      "type": "string",
      "description": "音轨引用（配音/配乐，单个），形态同 clips"
    },
    "size": {
      "type": "string",
      "description": "输出分辨率 WxH，默认 720x1280（竖版）"
    },
    "transition": {
      "type": "string",
      "enum": [
        "cut",
        "fade"
      ],
      "description": "转场方式，默认 cut"
    },
    "fade_seconds": {
      "type": "number",
      "description": "淡入淡出时长（秒），默认 0.5"
    }
  },
  "required": [
    "clips"
  ]
}

qc_check同步

对产物做规则质检。媒体模式：引用可解析（task_/asset_/URL//files/）、尺寸元数据齐备、画幅比例、最小分辨率、时长范围。编译产物审计模式：上游连 prompt_compile 时自动切换——复核正向词/负向词非空、镜号唯一、运动冲突、参数域与时长档（与编译器同一份 Profile 边界）。只报缺陷不改稿。strict=true 时任一项不过即抛错（工作流节点失败），false 时返回报告。同步执行，不耗积分。

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "质检目标：上游引用 key（如 v1.task_id）、task_ 任务号、asset_ 资产号、URL 或 /files/ 路径"
    },
    "strict": {
      "type": "boolean",
      "description": "不过即失败，默认 true"
    },
    "ratio": {
      "type": "string",
      "enum": [
        "auto",
        "9:16",
        "16:9",
        "1:1"
      ],
      "description": "画幅校验，默认 auto 不校验"
    },
    "min_width": {
      "type": "integer",
      "description": "最小宽度 px（可省略）"
    },
    "min_height": {
      "type": "integer",
      "description": "最小高度 px（可省略）"
    },
    "min_duration": {
      "type": "number",
      "description": "最短时长秒，仅视频/音频（可省略）"
    },
    "max_duration": {
      "type": "number",
      "description": "最长时长秒，仅视频/音频（可省略）"
    }
  },
  "required": [
    "target"
  ]
}

storyboard_split同步

分镜编剧（板块一）：把故事/剧本按剧情节拍拆成结构化文字分镜（每镜含主体/动作/景别/运动/声音/时长）。产出过硬结构校验器（缺主体/动作/景别、时长非法即失败），不生成任何媒体

{
  "type": "object",
  "properties": {
    "story": {
      "type": "string",
      "description": "故事/剧情（可含角色与场景设定）"
    },
    "duration": {
      "type": "integer",
      "description": "目标时长（秒），偏离超 10% 会带软警告"
    },
    "constraints": {
      "type": "string",
      "description": "额外约束：风格、画幅、角色设定等"
    }
  },
  "required": [
    "story"
  ]
}

storyboard_review同步

分镜审阅（板块二）：按连续性清单核查分镜草稿，只输出问题清单与结论——绝无改稿权，不产出分镜。未配 LLM 时降级为规则级审阅

{
  "type": "object",
  "properties": {
    "story": {
      "type": "string",
      "description": "故事/剧情（与分镜对照核查，省略则只做结构与自洽审阅）"
    },
    "shots": {
      "type": "string",
      "description": "待审分镜（数组或 storyboard_split 产出的 shots_json）"
    }
  },
  "required": [
    "shots"
  ]
}

prompt_compile同步

提示词编译（板块四）：把结构化分镜编译成目标模型可执行的提示词（逐镜正向词/负向词/参数）。按模型 Profile 出词（词汇域/参数边界/防畸变负面词逐模型独立）；硬校验器拦截参数越界与运动冲突（固定镜头×推拉摇移互斥），越界即失败不重试模型。只翻译表达，不改分镜意图

{
  "type": "object",
  "properties": {
    "shots": {
      "type": "string",
      "description": "结构化分镜（数组或 storyboard_split/integrate 产出的 shots_json）"
    },
    "model": {
      "type": "string",
      "description": "目标模型 id（gzm-image-1 / kling3 / seedance-2.5 / minimax-h3）"
    },
    "style": {
      "type": "string",
      "description": "风格约束（胶片感/画幅/色调等），并入正向词"
    },
    "constraints": {
      "type": "string",
      "description": "全局参数约束（比例/种子策略等）"
    }
  },
  "required": [
    "shots",
    "model"
  ]
}

image_dispatch同步

生图分配（板块五）：把编译产物规划成生图任务清单——每镜扇出宽度、seed 递进编排、并发上限（显存守护）。纯规则规划器不进模型，只产计划不执行（生成仍走 generate_image 执行节点）；镜头全覆盖/画幅合法越界即失败

{
  "type": "object",
  "properties": {
    "prompts": {
      "type": "string",
      "description": "编译产物（prompt_compile 的 prompts 键或逐镜数组）"
    },
    "model": {
      "type": "string",
      "description": "生图模型（默认 gzm-image-1）"
    },
    "variants": {
      "type": "integer",
      "description": "每镜出几张（1~4，默认 1）"
    },
    "max_concurrent": {
      "type": "integer",
      "description": "并发上限（1~4，显存守护，默认 2）"
    },
    "seed": {
      "type": "integer",
      "description": "基础种子，逐变体递进；缺省随机"
    }
  },
  "required": [
    "prompts"
  ]
}

video_dispatch同步

生视频分配（板块六）：把编译产物规划成视频任务清单——串行排队、首帧就绪优先（i2v 先跑）、单镜超时降级预案（超时回退定帧推镜并标 degraded，不自动重试）。纯规则规划器不进模型，只产计划不执行；时长必须在模型档位内，越界即失败

{
  "type": "object",
  "properties": {
    "prompts": {
      "type": "string",
      "description": "编译产物（prompt_compile 的 prompts 键或逐镜数组）"
    },
    "model": {
      "type": "string",
      "description": "视频模型（默认 minimax-h3）"
    },
    "first_frames": {
      "type": "string",
      "description": "逐镜首帧引用 JSON（{\"1\":\"img://...\"}），有首帧的镜优先排"
    },
    "max_concurrent": {
      "type": "integer",
      "description": "并发上限（1~2，默认 1 串行）"
    },
    "timeout_s": {
      "type": "integer",
      "description": "单镜超时秒（60~900，默认 480）"
    }
  },
  "required": [
    "prompts"
  ]
}

storyboard_integrate同步

分镜导演（板块三）：整合编剧分镜与审阅意见出终稿 + 待确认项。终稿同样过硬结构校验器，导演改坏稿时自动退回编剧草稿并在 pending 里说明

{
  "type": "object",
  "properties": {
    "story": {
      "type": "string",
      "description": "故事/剧情"
    },
    "shots": {
      "type": "string",
      "description": "编剧分镜（数组或 storyboard_split 产出的 shots_json）"
    },
    "review": {
      "type": "string",
      "description": "审阅意见（storyboard_review 产物，可省略）"
    },
    "constraints": {
      "type": "string",
      "description": "额外约束"
    }
  },
  "required": [
    "shots"
  ]
}