Skip to Content
无限画布节点类型 API

无限画布节点类型 API

用途

CLI 和外部客户端通过该接口动态发现无限画布支持的节点、端口与配置，避免在客户端硬编码枚举。

配图占位

  • 页面：无需界面截图，本页为 API 契约
  • 状态：使用终端或 API 客户端展示脱敏后的成功响应
  • 重点区域：schemaVersion、nodeTypes 和三个 schema 字段
  • 脱敏要求：不得展示 Cookie、Token 或用户数据

使用前准备

调用方必须携带有效的用户认证信息。该接口返回全局节点能力，不需要项目 ID，也不会读取或修改画布数据。

操作步骤

GET /api/canvas/node-types

成功响应：

{
  "data": {
    "schemaVersion": 2,
    "catalogRevision": "<sha256>",
    "nodeTypes": [
      {
        "kind": "image-generate",
        "title": "图片生成",
        "category": "GENERATION",
        "source": "builtin",
        "inputs": [],
        "outputs": [],
        "defaultConfig": { "prompt": "", "count": 1 },
        "taskType": "CANVAS_IMAGE_GENERATE",
        "inputSchema": { "type": "object", "properties": {}, "required": [] },
        "outputSchema": { "type": "object", "properties": {}, "required": [] },
        "configSchema": { "type": "object", "properties": {} }
      }
    ]
  }
}

CLI 应按 kind 识别节点，并按 schemaVersion 处理契约版本。inputSchema、outputSchema 和 configSchema 使用 JSON Schema Draft 2020-12。catalogRevision 在目录内容变化时更新，可用于刷新缓存。

兼容性约定

节点注册数据与历史画布节点分开存储，不会给既有画布节点补写版本字段。schema v2 保留 v1 的 data.nodeTypes 外层结构和所有内置节点字段，并增量提供 catalogRevision、source 及动态节点的 definitionId、definitionVersionId、双语标题和目录展示字段。兼容 v1/v2 的调用方应接受版本 1 或 2、忽略未知字段，并继续以 kind 作为节点身份。只有已发布且未归档的动态节点进入实时目录；响应不会暴露 Prompt 内容、映射或创建人信息。

结果与状态

  • inputs、outputs 保留端口名称、标签、类型、可选性和多值标记。
  • inputSchema、outputSchema 描述连线解析后的逻辑值；其中 x-canvas-port-type 是画布端口类型扩展。
  • configSchema 描述保存到 nodes[].data.config 的配置，并携带默认值和已知范围。
  • 输入值来自画布连线，不应作为 POST /api/projects/{projectId}/canvas/nodes/{nodeId}/execute 的请求体发送；执行接口没有业务请求体。

tts 节点的 CosyVoice 配置字段为 voice、languageHints、format、sampleRate、volume、cosyRate、pitch 和 instruction。configSchema.required 包含 voice，其字段说明会提示 cosyvoice-v3.5-plus 与 cosyvoice-v3.5-flash 只接受声音设计或声音克隆生成的同型号 ID；音色也可由 tts.voice 连线提供。rate 保留给非 CosyVoice 模型的通用语速调整。客户端应以接口返回的枚举和范围渲染控件，不要自行扩展格式、采样率或语言代码；执行端会按实际型号过滤语言提示，并仅允许 cosyvoice-v3.5-plus、cosyvoice-v3.5-flash 和 cosyvoice-v3-flash 使用最多 100 个计权字符的 instruction；保存配置中与有效模型不兼容的历史值会在执行时忽略。

voice-design 节点通过可选的 prompt 文本端口接收声音描述，通过 voice 文本端口输出音色 ID。其 configSchema 声明 prompt、previewText、prefix、targetModel 和 languageHints，产物资产标记为 voice-design.v1；该输出可直接连接到 tts.voice。

voice-clone 节点通过 audio 端口接收参考音频，通过 voice 文本端口输出音色 ID。其 configSchema 声明 prefix、targetModel、languageHints、maxPromptAudioLength 和 enablePreprocess；切换 targetModel 时应同步清除该型号不支持的 languageHints。产物资产标记为 voice-clone.v1。该输出连接到 tts.voice 后，执行端同时采用产物版本记录的百炼模型键，并兼容旧版产物使用的无供应商前缀模型键；只有该标记或可识别的旧版克隆格式会参与远端音色清理，克隆任务固定只提交一次。

权限和限制

未认证请求会返回认证错误。该接口只暴露系统级节点定义，不返回项目、资产、模型凭据或用户数据。

常见问题

为什么 schema 允许额外配置字段？

画布会保留 provider 或后续版本使用的配置字段。CLI 应优先使用 properties 中已声明的字段，并保留未知字段以兼容新版本。

节点枚举可以硬编码到 CLI 吗？

不建议。启动或刷新能力缓存时读取此接口，避免服务端新增节点后 CLI 枚举过期。

相关文档

Last updated on
节点参考动态节点注册与发布