{
  "schemaVersion": "2.0.0",
  "provider": "ShanMeng AI (闪梦AI)",
  "endpoint": "http://127.0.0.1:17800",
  "cloudEndpoints": {
    "primary": "https://www.shanmengai.com",
    "backup1": "https://www.shanmengai.cn",
    "backup2": "https://www.chatgpt2023.cn",
    "backupNote": "主站与备用镜像数据完全实时互通。如遇主站域名维护，创作者与 AI 助手可无缝切换至备用镜像继续调用。"
  },
  "authentication": {
    "type": "bearer",
    "header": "Authorization",
    "scheme": "Bearer",
    "tokenPrefix": "smk_",
    "exampleHeader": "Authorization: Bearer smk_************",
    "mcpEnvKey": "SHANMENG_AGENT_KEY",
    "howToObtain": "登录闪梦AI客户端 -> 点击顶栏「WorkBuddy / Agent 接入」-> 在「Agent 令牌管理」中生成并复制一次性明文令牌",
    "securityNotice": "Agent 令牌等价于当前登录账号权限，退出登录、切换账号或会员失效时自动吊销或拒绝；切勿公开外泄。",
    "errorHandling": [
      {
        "status": 401,
        "code": "agent_unauthorized",
        "action": "停下并提示用户在闪梦AI客户端重新登录，然后在顶栏弹窗生成新的 Agent 令牌并在请求头携带 Authorization: Bearer <令牌>。"
      },
      {
        "status": 403,
        "code": "membership_*",
        "action": "告知用户当前账号无对应会员权益或会员已过期，需在客户端开通或续费对应会员。"
      },
      {
        "status": 403,
        "code": "quota_exhausted",
        "action": "告知用户当前可用额度/次卡已耗尽，提示在客户端查看余额或补充额度；严禁换用其他工具伪造结果。"
      },
      {
        "status": 403,
        "code": "agent_feature_unregistered",
        "action": "告知用户该接口未在智能体白名单开放，禁止猜测或绕过接口；应改用本协议已列出的真实接口。"
      },
      {
        "status": 429,
        "code": "agent_rate_limited",
        "action": "提示用户调用过于频繁，放慢轮询频率（建议间隔 3~5 秒）后再试。响应体包含 resetAt 毫秒时间戳，应在恢复后再请求。",
        "resetAt": "响应字段包含 Unix 毫秒时间戳 resetAt，表示该时间戳之前请勿发起新请求"
      }
    ],
    "strictHonestyRule": "闪梦接口失败、返回错误码或额度不足时，必须如实向用户报告原因，绝不允许换用其他画图或视频工具产出内容冒充闪梦AI结果。"
  },
  "unavailableRoutes": [
    {
      "route": "GET /api/internal/readiness",
      "status": "不存在(404)",
      "useInstead": "GET /api/health/ready"
    },
    {
      "route": "GET /api/models/list",
      "status": "不存在(404)",
      "useInstead": "GET /api/dramas/models 或 GET /api/model-catalog"
    },
    {
      "route": "GET /v1/models",
      "status": "暂未开放(网关不代理 /v1/*)",
      "useInstead": "GET /api/model-catalog"
    },
    {
      "route": "POST /v1/images/generations",
      "status": "暂未开放(网关不代理 /v1/*)",
      "useInstead": "POST /api/dramas 或 POST /api/tasks"
    },
    {
      "route": "POST /v1/videos",
      "status": "暂未开放(网关不代理 /v1/*)",
      "useInstead": "POST /api/dramas 或 POST /api/tasks"
    },
    {
      "route": "GET /v1/videos/{id}",
      "status": "暂未开放(网关不代理 /v1/*)",
      "useInstead": "GET /api/dramas/{id}/jobs 或 GET /api/tasks/{id}"
    },
    {
      "route": "GET/POST /api/dramas/{id}/casts",
      "status": "不存在(404)",
      "useInstead": "GET /api/dramas/{id}/cast 与 PATCH /api/dramas/{id}/cast/{castId}"
    },
    {
      "route": "POST /api/dramas/{id}/casts/{castId}/portraits",
      "status": "不存在(404)",
      "useInstead": "PUT /api/dramas/{id}/cast/{castId}/image 或 POST /api/dramas/{id}/cast/{castId}/regenerate"
    },
    {
      "route": "GET/POST /api/dramas/{id}/episodes/{episodeId}/shots",
      "status": "不存在(404)",
      "useInstead": "GET /api/dramas/{id}/episodes/{episodeId} 与 PATCH /api/dramas/{id}/shots/{shotId}"
    },
    {
      "route": "POST /api/dramas/{id}/episodes/{episodeId}/export",
      "status": "不存在(404)",
      "useInstead": "POST /api/dramas/{id}/episodes/{episodeId}/jianying-draft"
    },
    {
      "route": "GET/POST /api/workbench/tools?kind=image|video",
      "status": "暂未开放(403)",
      "useInstead": "POST /api/dramas 或 POST /api/tasks"
    }
  ],
  "tools": [
    {
      "name": "check_readiness",
      "description": "检查本地闪梦AI（17801）服务是否就绪，需携带 Bearer Token。",
      "method": "GET",
      "url": "http://127.0.0.1:17800/api/health/ready",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {},
        "required": []
      }
    },
    {
      "name": "list_models",
      "description": "获取短剧可用的文本、图片、视频（如 shanmeng-h3-flex、shanmeng-h3-auto）模型列表与默认配置。",
      "method": "GET",
      "url": "http://127.0.0.1:17800/api/dramas/models",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {},
        "required": []
      }
    },
    {
      "name": "list_dramas",
      "description": "分页查询当前账号下的短剧项目列表。",
      "method": "GET",
      "url": "http://127.0.0.1:17800/api/dramas",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "default": 1
          },
          "pageSize": {
            "type": "integer",
            "default": 20
          },
          "q": {
            "type": "string",
            "description": "按名称模糊筛选"
          },
          "status": {
            "type": "string",
            "description": "按状态筛选"
          }
        },
        "required": []
      }
    },
    {
      "name": "create_drama",
      "description": "创建工业化短剧项目并可选择立即开始生产（自动拆解章节、提取角色/场景并生成视频）。",
      "method": "POST",
      "url": "http://127.0.0.1:17800/api/dramas",
      "headers": {
        "Authorization": "Bearer smk_************",
        "Content-Type": "application/json"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "短剧项目名称"
          },
          "sourceFormat": {
            "type": "string",
            "enum": [
              "novel",
              "script",
              "storyboard"
            ],
            "default": "script"
          },
          "chapters": {
            "type": "array",
            "description": "章节或分集原文列表",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                }
              },
              "required": [
                "text"
              ]
            }
          },
          "settings": {
            "type": "object",
            "properties": {
              "aspectRatio": {
                "type": "string",
                "enum": [
                  "9:16",
                  "16:9",
                  "1:1",
                  "3:4",
                  "4:3"
                ],
                "default": "9:16"
              },
              "episodeSeconds": {
                "type": "integer",
                "default": 30
              },
              "styleName": {
                "type": "string"
              },
              "stylePrompt": {
                "type": "string"
              },
              "mediaMode": {
                "type": "string",
                "enum": [
                  "auto",
                  "manual"
                ],
                "default": "auto"
              },
              "reviewMode": {
                "type": "string",
                "enum": [
                  "auto",
                  "sample",
                  "every"
                ],
                "default": "auto"
              }
            }
          },
          "start": {
            "type": "boolean",
            "default": true,
            "description": "创建后是否立即开始制作"
          }
        },
        "required": [
          "name",
          "chapters"
        ]
      }
    },
    {
      "name": "get_drama",
      "description": "获取短剧项目详情、剧集列表、角色/场景摘要及制作阶段。",
      "method": "GET",
      "url": "http://127.0.0.1:17800/api/dramas/{dramaId}",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "dramaId": {
            "type": "string"
          }
        },
        "required": [
          "dramaId"
        ]
      }
    },
    {
      "name": "start_drama",
      "description": "启动或继续执行指定短剧项目的生产流水线。",
      "method": "POST",
      "url": "http://127.0.0.1:17800/api/dramas/{dramaId}/start",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "dramaId": {
            "type": "string"
          }
        },
        "required": [
          "dramaId"
        ]
      }
    },
    {
      "name": "get_drama_cast",
      "description": "获取指定短剧已提取的角色阵容（含 castId、外貌设定与立绘资源 ID）。",
      "method": "GET",
      "url": "http://127.0.0.1:17800/api/dramas/{dramaId}/cast",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "dramaId": {
            "type": "string"
          }
        },
        "required": [
          "dramaId"
        ]
      }
    },
    {
      "name": "update_drama_cast",
      "description": "修改指定角色的设定、姓名、音色或提示词。",
      "method": "PATCH",
      "url": "http://127.0.0.1:17800/api/dramas/{dramaId}/cast/{castId}",
      "headers": {
        "Authorization": "Bearer smk_************",
        "Content-Type": "application/json"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "dramaId": {
            "type": "string"
          },
          "castId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "appearance": {
            "type": "string",
            "description": "角色外观与服装描摹"
          },
          "description": {
            "type": "string",
            "description": "角色人设描述"
          },
          "voiceInstructions": {
            "type": "string",
            "description": "配音语气/音色说明"
          },
          "locked": {
            "type": "boolean",
            "description": "是否锁定定妆"
          }
        },
        "required": [
          "dramaId",
          "castId"
        ]
      }
    },
    {
      "name": "get_episode_detail",
      "description": "获取单集详情、分镜镜头列表、剧情段视频生成状态与视频资源引用。",
      "method": "GET",
      "url": "http://127.0.0.1:17800/api/dramas/{dramaId}/episodes/{episodeId}",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "dramaId": {
            "type": "string"
          },
          "episodeId": {
            "type": "string"
          }
        },
        "required": [
          "dramaId",
          "episodeId"
        ]
      }
    },
    {
      "name": "export_jianying_draft",
      "description": "导出指定分集的剪映工程草稿 ZIP 包（表单提交 application/x-www-form-urlencoded）。",
      "method": "POST",
      "url": "http://127.0.0.1:17800/api/dramas/{dramaId}/episodes/{episodeId}/jianying-draft",
      "headers": {
        "Authorization": "Bearer smk_************",
        "Content-Type": "application/x-www-form-urlencoded"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "dramaId": {
            "type": "string"
          },
          "episodeId": {
            "type": "string"
          },
          "draftRoot": {
            "type": "string",
            "description": "可选，本机剪映草稿根目录"
          },
          "captions": {
            "type": "string",
            "enum": [
              "1",
              "0"
            ],
            "default": "1"
          }
        },
        "required": [
          "dramaId",
          "episodeId"
        ]
      }
    },
    {
      "name": "create_video_task",
      "description": "在任务中心提交异步生成任务（需在 input.config 中指定 system channelId 与 model）。",
      "method": "POST",
      "url": "http://127.0.0.1:17800/api/tasks",
      "headers": {
        "Authorization": "Bearer smk_************",
        "Content-Type": "application/json"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "projectId": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "如 canvas_video / video_text_to_video / video_image_to_video / canvas_image"
          },
          "operation": {
            "type": "string",
            "default": "text_to_video"
          },
          "prompt": {
            "type": "string"
          },
          "model": {
            "type": "string",
            "default": "shanmeng-h3-flex"
          },
          "input": {
            "type": "object",
            "description": "通常需包含 config: {channelId: 'CHANNEL_000002', model: 'shanmeng-h3-flex'}"
          }
        },
        "required": [
          "type",
          "prompt"
        ]
      }
    },
    {
      "name": "get_task_status",
      "description": "查询任务中心单个任务的实时进度、阶段状态与生成结果资源 ID。",
      "method": "GET",
      "url": "http://127.0.0.1:17800/api/tasks/{taskId}",
      "headers": {
        "Authorization": "Bearer smk_************"
      },
      "parameters": {
        "type": "object",
        "properties": {
          "taskId": {
            "type": "string"
          }
        },
        "required": [
          "taskId"
        ]
      }
    }
  ],
  "mcpConfigTemplate": {
    "command": "<SHANMENG_DIR>\\runtime\\python\\python.exe",
    "args": [
      "-s",
      "<SHANMENG_DIR>\\app\\studio\\shanmeng_mcp_server.py"
    ],
    "env": {
      "SHANMENG_ENDPOINT": "http://127.0.0.1:17800",
      "SHANMENG_AGENT_KEY": "smk_************"
    },
    "description": "闪梦AI工业化短剧生产引擎，基于 JSON-RPC 2.0 stdio 协议提供 10 项核心短剧与出片工具（HTTP 请直接访问 127.0.0.1:17800 OpenAPI）",
    "openapiUrl": "http://127.0.0.1:17800/openapi.json"
  },
  "securityBoundary": "令牌与启动凭证仅本机回环（127.0.0.1）有效，即使不小心将含令牌的接入文档发给他人或传到云端，也调不动他人电脑；本门禁防的是智能体与脚本零凭证直接调用，防不住同机同一用户权限下主动读取客户端数据目录的恶意程序。外部浏览器访问 127.0.0.1:17800 须在 /login 正常登录。"
}
