接入目录

Agent 接入

不用再一张张建卡、一根根连线，让智能体替你搭画布

剧本、角色、场景、分镜卡和它们之间的连线，一句话建好；生成前先报价，你点头才花钱；产物还能直接取回本地。画布和你在网页里看到的是同一张，AI 搭好的卡十几秒内就会出现在屏幕上，你只需要审核、针对性调整。

给 AI 编程助手：完整的机器可读接入说明在 /developers/llms.txt，请先读它再动手。其中 Skill 有完整版（rooyun）与精简版（也叫简易版，rooyun-cli，CLI 自由模式）两个版本：用户点名了就直接装那个，没点名先问用户要哪个。

方式一：把这页发给你的智能体

方式二：没有智能体？直接用创作助手

不用安装任何东西。打开任意一个项目，点画布右上角的「创作助手」，用中文说你想做什么——它同样会帮你建剧本、角色、场景和分镜卡，把线连好，生成前先报价。

从模板开一个项目适合不想装工具、或者只是偶尔用一下的时候

解决什么问题: 在画布上做一集，要一张张建剧本、角色、场景、分镜卡，再一根根连线，镜头一多满屏都是节点和线。接上 Agent 后，你只要说想做什么，它替你把卡片建好、线连好、生成提交好——你从「搭画布」里解放出来，只负责看结果、挑出不满意的地方改。
需要会写代码吗: 不需要。做短剧本来就不用写代码：有智能体就用方式一，把这页发给它；没有或不想装，就用方式二，直接在画布里用创作助手。

手动接入

方式一里智能体自己会做这三步；想自己动手、或智能体卡住了，再按下面来。

授权你的 AI

推荐让 AI 自己完成：装好 Skill 后它运行 dj login，你在弹出的页面登录并点一次「授权」，令牌就直接交给它并保存在你的电脑上—— 不用复制、不用配环境变量、以后所有会话通用。下面的按钮是手动创建令牌的备选路径。

令牌保存在哪、会用多久

dj login 把令牌写进你电脑的 ~/.rooyun/credentials.json（仅本用户可读；Windows 在 C:\Users\<你>\.rooyun\），macOS / Windows / Linux 同一位置。以后每个新会话、每个工具都自动读取，不用再配环境变量。令牌 365 天有效，到期再点一次授权即可。

授权签出的令牌是什么样

全部权限、不设消费限额（仍受钱包余额约束）。想划预算或做泄漏止损，到个人中心 → API 访问把限额改成正整数：额度用尽后新的生成会被拒绝，不会静默继续扣钱。「提交生成」与「剧本分析」都会花钱，后者单次成本低一到两个数量级。

想收窄权限或作废

到个人中心 → API 访问点该令牌的「编辑」，取消用不到的权限（例如只搭画布不取产物就去掉「资产读取」），下一次调用即时生效。要作废就点「吊销」，即时生效且不可撤销。

配置你的工具

下面的地址已按当前站点填好（$ROOYUN_BASE），复制后只需把令牌换成你自己的。

MCP 把 RooYun 的能力以「工具」的形式交给 Claude Code——不用你写任何胶水代码，它自己会调。在项目目录里执行一行命令即可：

claude mcp add --transport http rooyun $ROOYUN_BASE/api/mcp --header "Authorization: Bearer dj_pat_你的令牌"

把命令里的 dj_pat_你的令牌 换成第一步创建的令牌明文。不想把令牌落进 shell 历史，可以先 export DJ_TOKEN=… 再在命令里写 Bearer $DJ_TOKEN。

加完在 Claude Code 里执行 /mcp 应能看到 RooYun 已连接；连不上先回第三步验证令牌本身是否可用。

验证连通

接完先做一次自省，确认令牌真的可用——比在生成任务里撞 401 划算得多。

curl -s "$ROOYUN_BASE/api/v1/me" -H "Authorization: Bearer dj_pat_你的令牌"

预期返回令牌自身的信息：账号 id、令牌名、权限范围、有效期，以及带限额时的已用额度。看到它就说明鉴权链路通了。

json

{
  "ok": true,
  "data": {
    "userId": "452ea3ac-7c74-4e1f-8d19-79bc62d61f2d",
    "name": "本地 Claude Code",
    "scopes": ["projects:read", "canvas:write", "assets:read", "tasks:read", "generate"],
    "expiresAt": null,
    "spendLimitCredits": 200,
    "spentCredits": 12.46
  },
  "error": null
}

拿到 401 就按 error.code 分辨原因： token_invalid 是抄错了， token_revoked 是已吊销， token_expired 是过期了——后两种都得回网页端重建。

Capabilities

接进来之后，AI 能做什么

建项目与画布

画布写入

新建一个短剧项目并拿到画布句柄，或在既有项目里再开一张画布。

POST /api/v1/projects

13 个画布操作

画布写入

建卡（文本/角色/场景/道具/分镜）、连线与断线、改卡、把资产库里的产物绑回空卡、删卡、自动布局；整批原子，任一失败全批回滚。

POST /api/v1/canvases/{canvasId}/ops

读回画布结构

项目读取

拿到全部卡片、连线与身份锚（角色/场景/道具），以及下一批写入要用的 version。

GET /api/v1/canvases/{canvasId}/structure

详读单张卡片

项目读取

正文全文（不截断）、当前可写参数、分镜表全部行、直接上下游——精确改卡前先读它，读回什么就能改什么。

GET /api/v1/canvases/{canvasId}/nodes/{nodeId}

剧本 → 结构化角色 / 场景 / 道具

剧本分析

把一段剧本拆成带完整字段的角色、场景、道具数组，字段与建卡操作一一对应。只返回数据不落卡——改完再用 ops 写进画布。会消耗积分。

POST /api/v1/analyze/extract

剧本 → 结构化分镜

剧本分析

一个镜头出十几个字段：景别、运镜、构图、机位、焦段、时长、画面、起止状态、音轨、出场角色。拿回去改一行再写回，不必整表重来。会消耗积分。

POST /api/v1/analyze/storyboard

改写 / 优化 / 翻译 / 写词

剧本分析

按要求改写文本、把口语描述变成电影级生图提示词、中译英、给剧情写主题曲歌词。产物即文本，改完用 ops 回写卡片。会消耗积分。

POST /api/v1/analyze/rewrite

图片 / 视频反推提示词

剧本分析

参考图变成画面描述，参考片（自己抽好的 2–8 帧）变成完整镜头脚本。素材先上传换 assetId。会消耗积分：图片 0.1 积分/次、视频 0.1 积分/秒，失败自动退款。

POST /api/v1/analyze/caption

分镜图质检

剧本分析

判画面有没有崩坏、人物像不像定妆照、拍出来是不是导演要的。缺基准的维度不会假绿，会如实说「这一维没判」。每张 0.1 积分，失败退回，受限流。

POST /api/v1/analyze/inspect

模型目录与报价

任何有效令牌

查每个模型支持哪些能力、多少积分一次；未配价的模型会直说，省得白跑一趟。

GET /api/v1/models

音色目录

任何有效令牌

配音前先挑嗓子：平台预置音色 + 你自己的克隆/设计音色，可按关键词搜。

GET /api/v1/voices

花钱前先报价

提交生成

整批预检拿总价与余额，与网页端共用同一台报价机，口径逐分一致。

POST /api/v1/generations/precheck

提交生成与轮询

提交生成 · 任务查询

文生图 / 图生视频 / 配音 / 音乐等十种能力；指定卡片即定向落卡，产物自动写回画布。

POST /api/v1/generations · GET /api/v1/generations/{taskId}

数字人口播

提交生成

一段配音 + 一张肖像（或一条参考动作视频）→ 对口型的口播视频。口型与产出时长都由配音决定，只收 wav / mp3。数字人模型自成一档，不与普通图生视频混用。

POST /api/v1/generations（capability=avatar）

人工介入编辑

画布写入

撞上「只有人能指」的步骤（局部重绘要涂哪一块），签一条免登录编辑链接交给用户：他点开涂完提交，AI 取回蒙版接着做。链接等同凭据，15 分钟有效、提交即焚。

POST /api/v1/edit-sessions · GET /api/v1/edit-sessions/{id}

局部重绘

提交生成

拿蒙版只重画选中的那一块，其余像素锁定不变：文生图能力 + 源图 + 同尺寸 PNG 蒙版（透明像素 = 重绘区）。

POST /api/v1/generations（params.mask）

资产清单与下载

资产读取

列出项目引用的产物与云端缺件情况，按 assetId 取原件（302 签名地址，需跟随重定向）。

GET /api/v1/assets · GET /api/v1/assets/{assetId}/download

把产物绑回画布

画布写入

生成成功但产物只进了资产库（目标卡被删、或回写落卡失败）时，把它绑回卡片上，不必重新生成一次。只接受还没有产物的空卡——覆盖会让原产物被资产回收误删。

POST /api/v1/canvases/{canvasId}/ops（attachAsset）

上传本地素材

资产写入

把本机的图/视频/音频送进资产库，换回 assetId 当首帧、参考图或图生图源图；内容寻址，重复上传只占一份。

POST /api/v1/assets

钱包与账单

账单读取

看余额、冻结额与逐笔流水；按令牌过滤可自查这枚令牌到底烧了多少。

GET /api/v1/billing/wallet · GET /api/v1/billing/ledger

解析抖音博主 / 视频链接

博主分析读取

分享链接或口令全文 → 博主资料与作品列表元数据（主页列表已被抖音封禁，当前只回 secUid）（或单视频元数据）。不含播放直链；不扣积分，但打第三方上游，限流比读缓存紧。

POST /api/v1/creators/resolve

自己发起博主分析

博主分析读取

对一个博主发起深度分析（GPU 转写切镜 + 逐条多模态分析 + 账号归纳），返回任务句柄后轮询。整条链 30–60 分钟，故是异步的；每账号同时只允许一个在跑。每条样本视频 0.5 积分、账号归纳 1 积分，发起时扣齐，命中缓存或没做成的逐条退回。

POST /api/v1/creator-analyses · GET /api/v1/creator-analyses/{id}

拆解一条参考视频

博主分析读取

丢一条抖音单条视频进来，拿到逐镜头的「分段实现账」：每一镜在整片里承担什么叙事功能、对观众做了什么、复刻时哪些维度能换、画面具体做了什么。结构由一次全片分析产出、画面由逐镜分析产出（两层分工是实测出来的），约 5–15 分钟，异步轮询；带 requestId 可幂等。

POST /api/v1/reference-decompositions · GET /api/v1/reference-decompositions/{id}

按变换维度改编参考视频

生成

拿拆好的分段实现账改编成「同一套叙事结构、不同内容」的新片子：你说要换主播/产品/场景/垂类，服务端逐段按该段的「可换/必保」判定决定改不改——命中「必保」的那一段不改并如实标出（换了它这一段的功能就垮）。叙事功能、意图与段数全部保留，模型只写新台词与新画面要求。还会告诉你这条片子到底撑不撑得起你的诉求——某个维度过半的段都拒绝更换时直接判「撑不起」，并说明该换哪条对标片，免得你拿到一份自相矛盾的稿子还以为是模型没写好。同步返回，十几到几十秒。

POST /api/v1/reference-decompositions/{id}/adaptations

读博主画像与仿写提示词

博主分析读取

账号级 AI 画像全量报告：详细资料、风格雷达、标题公式与选题矩阵，以及可直接仿写的 stylePrompt / replicationGuide。仅限本账号在站内分析过的博主。

GET /api/v1/creators/{secUid}

读单视频报告与转写全文

博主分析读取

单条视频的多模态分析报告 + ASR 转写全文。授权覆盖你分析过的视频与博主画像的深度样本。

GET /api/v1/creators/{secUid}/videos/{videoId}/report

转存视频原片

资产写入 · 资产读取

把博主视频的原始文件拉进你的资产库，拿 assetId 走资产下载取回。抖音直链 2-4 周即失效，所以要转存而不是给链接；幂等，单文件 200MB、每账号 50 份上限。转存要「资产写入」、取文件要「资产读取」，两个权限都要勾。

POST /api/v1/creators/{secUid}/videos/{videoId}/archive

右上角标的是该能力需要的权限范围，与创建令牌时的勾选项一一对应。

Reference

完整契约与边界

全部端点的参数、请求体、响应形状与错误码枚举都在机器可读契约里，它由服务端从同一份校验器生成——文档说能传的，就是服务端真正接受的。

OpenAPI 3.1 契约（无需鉴权）Skill 与插件开源仓库（GitHub）Gitee 镜像

API 看到的是云端那一份

RooYun 是本地优先架构，真相在用户的浏览器里，云端是同步出来的副本。浏览器里尚未推送的编辑、未登录或未开云同步的项目、超过 50 MB 的资产，API 都看不到——不是接口坏了，是东西还在别的地方。

和浏览器同时编辑同一张画布不会损坏数据

用户本地没有未同步改动时，约二十秒内你落的卡自己出现在画布上，并提示「Agent 已更新画布」，页面不刷新、视口不动；本地有未同步改动时顶部出一条可停靠的横幅，不弹模态框、不打断编辑。

稳妥做法

优先在自己创建的画布上工作。确实要动用户正在编辑的那张，先读 structure 看清现状，然后直接写、不要带 ifVersion——不带才会在版本被推进时自动「重读 → 重放」，带上等于关掉这层保护，一撞就 409。