Deploy Blender Headless API

README.md

@@ -1,28 +1,104 @@
 ---
-title: Chinese To Malay Video Dubber CPU
-emoji: 🎬
+title: Blender Headless API
+emoji: 🦖
 colorFrom: blue
-colorTo: green
+colorTo: purple
 sdk: docker
-app_file: app.py
+app_port: 7860
 pinned: false
 ---
 
-# Chinese → Bahasa Melayu Video Dubber — CPU Basic
+# Blender Headless API
 
-Designed for Hugging Face Spaces CPU Basic (2 vCPU / 16 GB RAM).
+在 Hugging Face Space（CPU basic）上跑一个常驻的 FastAPI 服务，
+每次请求用 `blender --background --python worker.py` 无头执行一组
+白名单 3D 操作（建模 / 材质 / 灯光 / 相机 / 动画 / 渲染 / 导出），
+供 OpenClaw Agent 通过 HTTP 调用。
 
-Pipeline:
+## 目录结构
 
-Chinese MP4 → Whisper Small → Chinese → Malay translation → Meta MMS Malay TTS → FFmpeg → Malay MP4
+```
+.
+├── Dockerfile          # 安装 Blender + 启动 FastAPI
+├── requirements.txt
+├── app.py              # FastAPI 服务，接收请求，拉起 blender 子进程
+├── worker.py           # 运行在 Blender 内部（bpy）的操作分发器
+└── example_request.json
+```
 
-Models:
-- `openai/whisper-large-v3-turbo`
-- `Helsinki-NLP/opus-mt-zh-ms`
-- `facebook/mms-tts-zlm`
+## API
 
-This version does not clone the original speaker's voice. It is intentionally lightweight for CPU Basic.
+### `GET /health`
+检查服务和 Blender 二进制是否就绪。
 
-Recommended test: 1–3 minute videos. Longer videos can take a long time on CPU.
+### `POST /execute`
+```json
+{
+  "scene_b64": null,
+  "ops": [
+    {"op": "create_object", "type": "sphere", "name": "Ball", "location": [0,0,1]},
+    {"op": "add_material", "target": "Ball", "color": [0.8, 0.1, 0.1, 1.0], "roughness": 0.3},
+    {"op": "add_light", "type": "SUN", "location": [4,-4,6], "energy": 3},
+    {"op": "set_camera", "location": [6,-6,4], "look_at": [0,0,1]},
+    {"op": "set_render_settings", "resolution": [960, 540], "samples": 32},
+    {"op": "render_image", "filename": "ball.png"},
+    {"op": "export_glb", "filename": "ball.glb"}
+  ]
+}
+```
 
-FFmpeg/ffprobe are required by the Space runtime.
+返回：
+```json
+{
+  "job_id": "a1b2c3d4e5f6",
+  "ops_result": {"ok": true, "results": [...], "errors": []},
+  "files": ["ball.png", "ball.glb"],
+  "download_base": "/files/a1b2c3d4e5f6/"
+}
+```
+
+### `GET /files/{job_id}/{filename}`
+下载生成的文件（渲染图 / glb / fbx / blend）。
+
+### `DELETE /jobs/{job_id}`
+清理某次任务的临时文件。
+
+## 支持的 op（在 `worker.py` 里维护白名单）
+
+| op | 说明 |
+|---|---|
+| `create_object` | 创建基础几何体（sphere/cube/cylinder/cone/plane/monkey/torus/empty） |
+| `move_object` | 绝对位置或相对位移 |
+| `set_transform` | 设置位置/旋转(度)/缩放 |
+| `add_material` | 创建/应用材质（颜色、金属度、粗糙度） |
+| `set_camera` | 创建相机，支持 look_at 自动朝向 |
+| `add_light` | 创建灯光（POINT/SUN/AREA/SPOT） |
+| `add_animation` | 按关键帧设置位置/旋转/缩放 |
+| `set_render_settings` | 分辨率/引擎/采样数/帧率/起止帧 |
+| `render_image` | 渲染单帧 PNG |
+| `render_animation` | 渲染动画序列帧 |
+| `import_model` | 导入 glb/gltf/fbx/obj |
+| `export_glb` / `export_fbx` | 导出模型 |
+| `delete_object` | 删除物体 |
+| `save_blend` | 保存 .blend 文件 |
+
+不支持任意 Python 执行——Agent 只能组合调用这些 op，避免生成失控脚本
+（死循环、超大渲染、越权文件访问）。
+
+## 部署前需要改的地方
+
+1. `Dockerfile` 里的 `BLENDER_VERSION`，默认是 `4.2.9`（4.2 LTS 最新补丁版）。
+   如需其他版本，去 https://download.blender.org/release/ 确认对应文件名。
+2. `JOB_TIMEOUT_SECONDS`（Dockerfile 里的环境变量），默认 180 秒，
+   渲染复杂场景时按需调大——但 HF Space CPU basic 的算力有限，
+   建议先用低分辨率/低采样数验证流程。
+3. 认证：这个 MVP 没有做鉴权，Space 一旦公开任何人都能调用你的 `/execute`。
+   建议在 `app.py` 加一个简单的 API Key header 校验（`X-API-Key`），
+   OpenClaw 那边配置对应的 key。
+
+## OpenClaw 集成建议
+
+按你之前的设计，把它包成一个 skill：
+`blender_execute` = bash wrapper 拼装 ops.json → POST 到这个 Space 的
+`/execute` → 轮询/直接拿到 `files` 列表 → 用 `GET /files/...` 下载渲染结果
+或 glb，交给你现有的 video-gen / 3d-video pipeline 继续处理。