RooYun/ 开发者接入

Developers

让你的 AI 编程助手
直接驱动 RooYun

建画布、拆分镜、调模型生成、把产物取回本地——全程不用打开浏览器。画布和你在网页里看到的是同一张，AI 落的卡二十秒内就会出现在屏幕上。

Claude CodeCursorCodex任何有 curl 的工具

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

授权你的 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

分镜图质检

剧本分析

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

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 分钟，故是异步的；每账号同时只允许一个在跑；不扣积分。

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 契约（无需鉴权）完整开发者文档见仓库 docs/API_V1.md

API 看到的是云端那一份

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

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

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

稳妥做法

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

让你的 AI 编程助手直接驱动 RooYun

授权你的 AI

配置你的工具

验证连通

接进来之后，AI 能做什么

建项目与画布

13 个画布操作

读回画布结构

详读单张卡片

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

剧本 → 结构化分镜

改写 / 优化 / 翻译 / 写词

图片 / 视频反推提示词

分镜图质检

模型目录与报价

音色目录

花钱前先报价

提交生成与轮询

数字人口播

人工介入编辑

局部重绘

资产清单与下载

把产物绑回画布

上传本地素材

钱包与账单

解析抖音博主 / 视频链接

自己发起博主分析

拆解一条参考视频

按变换维度改编参考视频

读博主画像与仿写提示词

读单视频报告与转写全文

转存视频原片

完整契约与边界

让你的 AI 编程助手
直接驱动 RooYun