Cineweave (影织)

Open-source AI cinematic workflow platform for short-drama production (BYOK-first).

影织（Cineweave） 是一个面向短剧/影视内容生产的开源工作流平台，当前采用 BYOK（Bring Your Own Key，自带 API Key） 模式，帮助团队把剧本、分镜、素材准备、视频生成、QA、治理与发布流程串起来。

Project Status / 项目状态

• Status: Alpha
• Positioning: workflow platform + provider adapter framework
• Model: open-source + BYOK

This repository is suitable for:

• local development / self-hosted deployment
• internal team workflow prototyping
• provider adapter integration (Runway / Kling / Seedance / etc.)

This repository is not yet a turnkey hosted SaaS that guarantees a full “novel → final video” production pipeline.

Features / 特性

• Cinematic workbench UI (apps/web-v2) with 24 workflow modules
• Global API connection center (connected / warming up / unreachable / invalid API)
• Provider adapter framework (apps/api/src/providers/*)
• BYOK-first provider settings and diagnostics
• Provider error normalization and user-facing actionable messages
• Reference deployment setup (Vercel frontend + Render backend)
• healthz / capabilities endpoints for environment diagnostics

Monorepo Layout / 仓库结构

• apps/web-v2 — React + Vite workbench UI
• apps/api — Express-based orchestration API
• docs — deployment docs, BYOK docs, specs, runbooks

Quick Start / 快速开始（本地）

1) Install dependencies / 安装依赖

npm install
cd apps/web-v2 && npm install
cd ../api && npm install

2) Configure environment / 配置环境变量

Backend example:

cp apps/api/.env.example apps/api/.env

Frontend example:

cp apps/web-v2/.env.example apps/web-v2/.env

3) Start backend API / 启动后端

cd apps/api
npx tsx src/server.ts

Default local API:

• http://localhost:3001

4) Start frontend UI / 启动前端

cd apps/web-v2
npm run dev

Default local UI:

• http://localhost:5173

BYOK (Bring Your Own Key) / 自带 API Key 模式

Cineweave currently uses a BYOK-first model:

• You provide your own provider credentials (Kling / Runway / Seedance, etc.)
• Cineweave provides workflow orchestration, UI, task handling, and adapter integration
• Provider token/credit consumption belongs to your provider account

Where to put keys / Key 放在哪里

Backend only (Render / server runtime):

• KLINGAI_ACCESS_KEY / KLINGAI_SECRET_KEY (or KLING_ACCESS_KEY / KLING_SECRET_KEY)
• RUNWAY_API_KEY (when enabled)
• SEEDANCE_API_KEY (when enabled)

Frontend (Vite)

• VITE_CINEWEAVE_API_BASE — API base URL only

Do not put provider secrets in frontend environment variables.

BYOK docs / BYOK 文档

• docs/providers/byok-setup.md

Common troubleshooting entry points:

• Kling 401 (AK/SK / signing / env placement)
• Kling 1102 (provider account-layer issue: credits / permissions / workspace context)
• Vercel vs Render env placement (VITE_CINEWEAVE_API_BASE on Vercel, provider keys on Render)

Deployment / 部署指南

Local / 本地部署

Use the Quick Start section above.

Reference Cloud Deployment (Vercel + Render) / 参考云部署

• Frontend: Vercel (Hobby)
• Backend: Render (Free Web Service)

Reference docs:

• docs/deployment/render-vercel-quickstart.md
• docs/deployment/naming-and-environment-policy.md

Notes:

• This is a reference deployment for demo/testing.
• Render free instances may spin down and introduce cold-start delays.

What Works / 当前可用能力

• Workbench UI and workflow navigation
• Global API connectivity diagnostics
• Provider adapter framework
• Kling real API connectivity path (submit + poll implemented)
• BYOK provider settings diagnostics (including key source visibility)

In Progress / 进行中

• Stable end-to-end “novel → final video” production flow
• Multi-provider production-grade coverage
• Persistence, background jobs, and stronger cost controls

Contributing / 贡献指南

• Read CONTRIBUTING.md before opening a PR
• Use the issue templates under .github/ISSUE_TEMPLATE/
• For security issues, follow SECURITY.md (do not open public issues for sensitive reports)

License / 开源许可证

This repository currently uses Apache 2.0.

• LICENSE

If the project license changes in the future (e.g. MIT), it will be announced in the repository and release notes.