REST API（v1）

Base URL：https://ivideo.run/v1

認證

所有端點（除 /health）需要 Authorization: Bearer <token>：

• 登入取得的 access token，或 ivideo.run/token 領取的長效權杖（hsvm_…，90 天）
• 未認證回 401

通用約定

• 資源 ID 帶前綴：prj_ 專案、seg_ 片段、sub_ 字幕塊、aud_ 音訊、mod_ 模組、ast_ 素材、apl_ 套用實例、sty_ 風格
• 驗證錯誤（400/422）為機器可讀格式：{"errors":[{"path":"segments[0].source.out","error":"out 必須大於 in"}]}——照 path 修正後重送
• 文件寫入採樂觀鎖：409 表示版本過期，重新讀取後再套用修改

端點

健康檢查

GET/v1/health → {"ok":true}（免認證）

會員

GET/v1/members/me → 登入者資料（displayName、avatarUrl、role：admin／member／paid）

專案

POST/v1/projects {title?} → 201 專案（含空文件 doc 與 docVersion:1）

GET/v1/projects → 自己的專案列表

GET/v1/projects/:id → 單一專案；非擁有者 404

專案文件（單一真相 JSON）

GET/v1/projects/:id/doc → {doc, docVersion}

PUT/v1/projects/:id/doc {doc, baseVersion} → {docVersion, diff}；diff.summary 如「片段：變更 2；字幕塊：新增 1」。422 驗證失敗、409 版本過期

{
  "project":  { "id": "prj_8f2k…", "version": 1, "fps": 30, "resolution": "1920x1080" },
  "segments": [{ "id": "seg_…", "source": { "assetId": "ast_…", "in": 0, "out": 3.2 },
                 "modules": [{ "id": "apl_…", "moduleId": "mod_…", "version": "1.0.0",
                               "params": {}, "assets": {} }] }],
  "subtitles": [{ "id": "sub_…", "text": "…", "start": 1.2, "end": 2.8, "module": null }],
  "audio":     [{ "id": "aud_…", "type": "sfx", "moduleId": "mod_…", "at": 3.2, "volume": 0.8 }]
}

時間軸操作

POST/v1/projects/:id/timeline/segments {assetId, in, out} → {segmentId, docVersion}

POST/v1/projects/:id/timeline/split {segmentId, at} → 下刀；左段保留原 id、右段新 id、模組複製

POST/v1/projects/:id/timeline/reorder {order: [segId…]} → 拖曳排序（id 集合須一致）

POST/v1/projects/:id/timeline/apply-module {segmentId, moduleId, version, params?}

素材

POST/v1/projects/:id/assets {kind: video|image|gif|audio, filename} → 201 {id, uploadUrl, storagePath}；用 HTTP PUT 把檔案傳到 uploadUrl

POST/v1/assets/:id/complete {durationS?, width?, height?} → 標記就緒

模組

POST/v1/modules/validate <manifest> → {ok, errors}（不儲存）

POST/v1/modules <manifest> → 201 {id, version}；同 id 同版本 409（遞增 version 才能更新）

GET/v1/modules ?category= → 自己的模組

GET/v1/modules/:id → 自己的或已發佈的模組

POST/v1/modules/:id/publish {published?} → 發佈到市集／下架

風格（模組集合）

POST/v1/styles {name, description?} → 201 {id: "sty_…"}

GET/v1/styles → 自己的 + 被分享的風格

GET/v1/styles/:id → 風格 + 內含模組（完整 manifest）

POST/v1/styles/:id/modules {moduleId} → 把模組收進風格（限擁有者）

DELETE/v1/styles/:id/modules/:moduleId → 移出風格

POST/v1/styles/:id/share {email} → 以 email 分享給其他會員（唯讀）

規劃中

自動字幕（/subtitles）、市集搜尋（/marketplace）、雲端輸出（/renders，付費）——上線後於此補充。