From e37597f4329f6d2790423e7e2d98cf74f806a2f0 Mon Sep 17 00:00:00 2001 From: stupid-h4er Date: Tue, 26 May 2026 23:10:57 +0800 Subject: [PATCH] docs: add ark agentplan setup notes --- README.md | 2 +- docs/canvas-node-manual.md | 5 ++++- docs/features.md | 22 ++++++++++++++++++++-- docs/pending-test.md | 3 +++ 4 files changed, 28 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f7553b8..4557645 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ## 核心功能 - 无限画布：多画布项目、节点拖拽缩放、连线、小地图、撤销重做、导入导出。 -- AI 创作：支持 OpenAI 兼容接口的文生图、图生图、参考图编辑和文本问答。 +- AI 创作：支持 OpenAI 兼容接口的文生图、图生图、参考图编辑、文本问答和视频生成；Seedance 2.0 可通过火山方舟 Agent Plan 接入。 - 画布助手：围绕选中节点和上游节点对话、生图，并把结果插回画布。 - 提示词库：抓取多个 GitHub 开源项目，按案例整理数百个图片提示词。 diff --git a/docs/canvas-node-manual.md b/docs/canvas-node-manual.md index 845b9a6..48db9b8 100644 --- a/docs/canvas-node-manual.md +++ b/docs/canvas-node-manual.md @@ -45,7 +45,10 @@ - 视频节点使用原生播放器展示内容，可在节点内直接播放、暂停和拖动进度。 - 空视频节点下方对话框可输入提示词生成视频，结果会回填到当前节点。 - 从文本、图片或配置节点创建视频生成时，会在右侧生成新的视频节点并自动连接。 -- 视频生成接口使用 OpenAI 兼容的 `POST /v1/videos`、`GET /v1/videos/{id}` 和 `GET /v1/videos/{id}/content`。 +- 生成配置节点的视频模式会读取上游文本作为 prompt，读取上游图片作为参考图，读取上游视频作为参考视频，并在输入预览里显示参考视频。 +- 视频生成接口支持 OpenAI 风格的 `POST /v1/videos`、`GET /v1/videos/{id}` 和 `GET /v1/videos/{id}/content`。 +- 使用火山方舟 Agent Plan / Seedance 2.0 时，Base URL 配置为 `https://ark.cn-beijing.volces.com/api/plan/v3`，模型名使用 Seedance 2.0 对应模型；系统会改用 `POST /contents/generations/tasks` 创建异步任务，并轮询 `GET /contents/generations/tasks/{id}`。 +- Seedance 参考视频必须是公网可访问 URL，或由本项目后端在配置 `PUBLIC_BASE_URL` 后上传并暴露的参考素材 URL。本地/内网地址无法被火山服务器拉取。 ### 推荐流程 diff --git a/docs/features.md b/docs/features.md index bec3f05..344dd90 100644 --- a/docs/features.md +++ b/docs/features.md @@ -52,13 +52,25 @@ ## AI 生成 -项目通过前端直接请求 OpenAI 兼容接口： +项目支持两种 AI 调用方式： + +- 本地直连：前端使用本地配置的 Base URL、API Key 和 Model 直接请求 OpenAI 兼容接口。 +- 后台渠道：前端请求本项目后端 `/api/v1/*` 代理接口，后端按模型选择管理后台配置的渠道。 + +OpenAI 兼容图像和文本能力继续复用现有接口： - `/v1/images/generations`：文生图。 - `/v1/images/edits`：图生图/参考图编辑。 - `/v1/chat/completions`：文本问答和带图问答。 - `/v1/models`：读取模型列表。 +视频能力支持两类接口： + +- OpenAI 风格视频：`POST /v1/videos`、`GET /v1/videos/{id}`、`GET /v1/videos/{id}/content`。 +- 火山方舟 Agent Plan / Seedance 2.0：Base URL 使用 `https://ark.cn-beijing.volces.com/api/plan/v3`，创建任务为 `POST /contents/generations/tasks`，查询任务为 `GET /contents/generations/tasks/{id}`，成功结果读取 `content.video_url`。 + +Base URL 如果已经以 `/v1`、`/api/v3` 或 `/api/plan/v3` 结尾，系统不会再追加 `/v1`。因此 cpa 反代或火山方舟 Agent Plan 可以继续通过现有 Base URL + API Key + Model 方式配置，不需要新增火山生图 Provider。 + 可配置项： - Base URL。 @@ -67,9 +79,13 @@ - 图片质量。 - 图片比例。 - 生成数量。 +- 视频模型。 +- 视频比例、清晰度和时长。 普通图片/文本节点可以直接输入提示词生成结果。生成配置节点可以读取上游节点内容，并按节点自己的配置批量生成多个图片或文本结果。生成配置节点支持预览当前提示词和参考图输入，并调整输入顺序。 +视频生成可从文本节点读取 prompt，从图片节点读取参考图，从视频节点读取参考视频。生成成功后会把视频插入画布为视频节点并使用原生播放器预览。Seedance 参考视频需要公网可访问 URL；本地上传视频会先通过 `/api/v1/media/references` 保存到服务端，再由 `PUBLIC_BASE_URL` 生成可供火山服务器拉取的公开链接。 + ## 画布助手 画布右侧助手面板支持： @@ -161,6 +177,8 @@ ## 当前限制 - 画布项目和“我的素材”目前只保存在浏览器本地，不会随账号同步。 -- AI API Key 目前保存在浏览器本地，并由浏览器直接请求配置的 OpenAI 兼容接口。 +- 本地直连模式下，AI API Key 保存在浏览器本地，并由浏览器直接请求配置的 OpenAI 兼容接口；只适合本地或个人使用，公网多人使用不安全。公网部署推荐使用后台渠道，把真实密钥保存在服务端配置中。 - 服务器素材库目前主要保存 URL 或文本，暂未提供文件上传接口。 +- Seedance 本地参考图/视频上传依赖 `PUBLIC_BASE_URL`，如果服务部署在 localhost、内网或不可被火山访问的地址，火山无法拉取参考素材。 +- Seedance 返回远程视频 URL 时，前端会尽量下载为本地 Blob 持久化；如果因 CORS 或网络限制无法下载，会保留远程 URL，后续是否可播放取决于上游 URL 的有效期。 - 画布更适合桌面端使用，移动端触控体验还未系统完善。 diff --git a/docs/pending-test.md b/docs/pending-test.md index 5867f38..3b1a416 100644 --- a/docs/pending-test.md +++ b/docs/pending-test.md @@ -21,3 +21,6 @@ - 视频生成前端会识别后端 `{ code, msg }` 错误响应，创建失败不再继续轮询 `undefined`。 - 新增 `/video` 视频创作台页面，参考生图工作台布局，支持提示词、参考图、视频参数、生成结果、保存素材、下载和本地生成记录；清晰度和秒数均支持常用值选择与手动输入，生成记录只保存媒体 `storageKey` 并可回填本次提示词、参考图和参数。 - 视频创作台生成前会把模型、尺寸、秒数、清晰度归一化为视频接口支持的参数，并展示后端返回的错误信息，避免页面侧残留的生图参数影响视频请求。 +- 火山方舟 Agent Plan / Seedance 2.0 视频生成需要在真实账号下验证：`/contents/generations/tasks` 创建任务、轮询状态、`content.video_url` 回填画布，以及 401/403/429/超时错误提示。 +- `PUBLIC_BASE_URL` 已配置公网域名时，需要验证本地上传参考视频能被火山拉取；未配置或配置为内网地址时，需要验证前端能给出明确提示。 +- Seedance 返回远程视频 URL 但浏览器无法下载为 Blob 时，需要验证视频节点刷新后仍保留远程 URL，并确认上游 URL 有效期限制。