{
  "openapi": "3.0.3",
  "info": {
    "title": "N0V 媒体工作台 API",
    "version": "1.0",
    "description": "从提示词到成片：提交生成任务，连续读取视频与事件，再将字幕轨和视频整理为可交付的资源。公共资源目录可直接读取，工作区请求使用 Bearer 令牌。\n\n## 视频生成流程\n\n1. 工作区客户端申请短期令牌。创建生成任务需要 `generation:write`，读取已有任务需要 `generation:read`。\n2. 向 `POST /api/v1/seedance` 提交提示词与画幅，保持事件流打开。每个生成任务都有独立的事件序列。\n3. 客户端按序消费上游产生的视频分片，同时处理进度、字幕和素材登记指令。断线后凭任务 ID 和最后处理的事件 ID 继续读取。\n4. 终态事件结束会话。成功后可按字节范围读取成片；字幕轨与交付记录独立提供。\n\n## 公开资源目录\n\n```sh\ncurl -fsS https://api.n0v.top/reference/service.json\n```\n\n响应中的 `resources` 指向公开索引。读取时保存 `ETag`，下次可用 `If-None-Match` 做条件请求。状态码 304 表示原副本仍有效。可直接下载 [OpenAPI 3.0.3 定义](/reference/openapi.json)。\n"
  },
  "servers": [
    {
      "url": "https://api.n0v.top",
      "description": "工作区与公共资源"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "服务描述",
      "description": "获取文档格式版本、文档首页以及资源索引的位置。"
    },
    {
      "name": "资源索引",
      "description": "按条目标识查找资源，使用条目中的 `href` 读取对应文件。"
    },
    {
      "name": "目录快照",
      "description": "快照保留选定资源及其排列顺序。使用同一快照 ID 读取摘要、分页遍历条目，或在稍后复查这次选择。"
    },
    {
      "name": "视频生成",
      "description": "提交镜头描述，跟踪任务进度并控制任务生命周期。"
    },
    {
      "name": "事件与视频",
      "description": "续接任务的事件流，按顺序读取视频分片，或下载完整 MP4。"
    },
    {
      "name": "素材管理",
      "description": "导入小型图片素材，查询内容摘要与元数据，并以游标分页浏览素材列表。"
    },
    {
      "name": "分镜编排",
      "description": "以连续时间码编排镜头，关联生成任务与素材，保持完整时间线与总时长一致。"
    },
    {
      "name": "字幕轨道",
      "description": "保存字幕时间轴，查询文本与时间码，并导出标准 WebVTT 字幕文件。"
    },
    {
      "name": "工作区鉴权",
      "description": "服务端应用使用客户端凭据申请短期工作区令牌，可查询令牌作用范围和到期时间。"
    },
    {
      "name": "Agent 指令与回执",
      "description": "在长连接中收到的指令也可从收件箱读取。用指令 ID 去重，然后提交客户端回执。"
    },
    {
      "name": "交付与用量",
      "description": "交付记录引用已经完成的生成任务和可选字幕；用量按工作区和 UTC 时间范围统计。"
    }
  ],
  "paths": {
    "/reference/service.json": {
      "get": {
        "operationId": "getService",
        "summary": "获取服务描述",
        "responses": {
          "200": {
            "description": "服务名称、格式版本和入口路径",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Service"
                },
                "example": {
                  "schema_version": "1.0",
                  "name": "N0V 公共资源目录",
                  "documentation": "/",
                  "resources": "/reference/resources.json"
                }
              }
            },
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          }
        },
        "tags": [
          "服务描述"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "description": "读取文档格式版本及两个入口。`documentation` 是面向读者的首页，`resources` 是供程序读取的 JSON 索引。",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "读取 JSON",
            "source": "curl -fsS https://api.n0v.top/reference/service.json"
          },
          {
            "lang": "curl",
            "label": "条件读取",
            "source": "curl -fsS --etag-save service.etag https://api.n0v.top/reference/service.json\ncurl -sS -i --etag-compare service.etag https://api.n0v.top/reference/service.json"
          }
        ]
      },
      "head": {
        "operationId": "headService",
        "summary": "读取服务描述的响应头",
        "responses": {
          "200": {
            "$ref": "#/components/responses/HeadOK"
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          }
        },
        "tags": [
          "服务描述"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "description": "检查资源是否可读取；客户端可从响应头取得 `ETag`，用于下一次条件请求。",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "读取响应头",
            "source": "curl -sSI https://api.n0v.top/reference/service.json"
          }
        ]
      }
    },
    "/reference/resources.json": {
      "get": {
        "operationId": "getResources",
        "summary": "获取资源索引",
        "responses": {
          "200": {
            "description": "公开 JSON 资源列表",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceIndex"
                },
                "example": {
                  "items": [
                    {
                      "id": "service",
                      "title": "服务描述",
                      "href": "/reference/service.json",
                      "media_type": "application/json"
                    },
                    {
                      "id": "resources",
                      "title": "资源索引",
                      "href": "/reference/resources.json",
                      "media_type": "application/json"
                    },
                    {
                      "id": "openapi",
                      "title": "OpenAPI 接口定义",
                      "href": "/reference/openapi.json",
                      "media_type": "application/json"
                    }
                  ]
                }
              }
            },
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          }
        },
        "tags": [
          "资源索引"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "description": "遍历 `items`，用 `id` 选择资源，再将其 `href` 与服务域名组合。条目顺序不参与查找。",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "读取 JSON",
            "source": "curl -fsS https://api.n0v.top/reference/resources.json"
          },
          {
            "lang": "curl",
            "label": "条件读取",
            "source": "curl -fsS --etag-save resources.etag https://api.n0v.top/reference/resources.json\ncurl -sS -i --etag-compare resources.etag https://api.n0v.top/reference/resources.json"
          }
        ]
      },
      "head": {
        "operationId": "headResources",
        "summary": "读取资源索引的响应头",
        "responses": {
          "200": {
            "$ref": "#/components/responses/HeadOK"
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          }
        },
        "tags": [
          "资源索引"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          }
        ],
        "description": "检查资源是否可读取；客户端可从响应头取得 `ETag`，用于下一次条件请求。",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "读取响应头",
            "source": "curl -sSI https://api.n0v.top/reference/resources.json"
          }
        ]
      }
    },
    "/api/v1/snapshots": {
      "post": {
        "tags": [
          "目录快照"
        ],
        "operationId": "createCatalogSnapshot",
        "summary": "创建目录快照",
        "description": "按 resource_ids 的传入顺序保存资源列表。重复的资源标识不允许出现在同一请求中。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSnapshot"
              },
              "example": {
                "resource_ids": [
                  "service",
                  "resources"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "快照已保存，响应包含标识和条目总数。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                },
                "example": {
                  "snapshot_id": "snap_docs_01",
                  "resource_ids": [
                    "service",
                    "resources"
                  ],
                  "total": 2
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "请求示例",
            "source": "curl -i -H \"Authorization: Bearer ${TOKEN}\" -X POST -H 'Content-Type: application/json' \\\n  --data '{\"resource_ids\":[\"service\",\"resources\"]}' \\\n  https://api.n0v.top/api/v1/snapshots"
          }
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ]
      }
    },
    "/api/v1/snapshots/{snapshot_id}": {
      "get": {
        "tags": [
          "目录快照"
        ],
        "operationId": "getCatalogSnapshot",
        "summary": "查询快照摘要",
        "description": "按 snapshot_id 查找快照。total 始终表示整份快照的条目数。",
        "parameters": [
          {
            "$ref": "#/components/parameters/SnapshotId"
          }
        ],
        "responses": {
          "200": {
            "description": "快照摘要。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                },
                "example": {
                  "snapshot_id": "snap_docs_01",
                  "resource_ids": [
                    "service",
                    "resources"
                  ],
                  "total": 2
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "请求示例",
            "source": "curl -i -H \"Authorization: Bearer ${TOKEN}\" https://api.n0v.top/api/v1/snapshots/snap_docs_01"
          }
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ]
      }
    },
    "/api/v1/snapshots/{snapshot_id}/entries": {
      "get": {
        "tags": [
          "目录快照"
        ],
        "operationId": "listCatalogSnapshotEntries",
        "summary": "分页读取快照条目",
        "description": "首次请求省略 cursor；继续读取时原样传入上页的 next_cursor。末页返回 null。",
        "parameters": [
          {
            "$ref": "#/components/parameters/SnapshotId"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "每页最多返回的条目数量。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "example": 1
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "翻页时使用上次响应给出的非空游标。首次请求省略。",
            "schema": {
              "type": "string"
            },
            "example": "c_AQ"
          }
        ],
        "responses": {
          "200": {
            "description": "当前页条目与下一页游标。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SnapshotPage"
                },
                "examples": {
                  "first": {
                    "summary": "首页（limit=1）",
                    "value": {
                      "snapshot_id": "snap_docs_01",
                      "items": [
                        {
                          "id": "service",
                          "title": "服务描述",
                          "href": "/reference/service.json",
                          "media_type": "application/json"
                        }
                      ],
                      "total": 2,
                      "next_cursor": "c_AQ"
                    }
                  },
                  "last": {
                    "summary": "末页（带游标）",
                    "value": {
                      "snapshot_id": "snap_docs_01",
                      "items": [
                        {
                          "id": "resources",
                          "title": "资源索引",
                          "href": "/reference/resources.json",
                          "media_type": "application/json"
                        }
                      ],
                      "total": 2,
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "首页",
            "source": "curl -i -H \"Authorization: Bearer ${TOKEN}\" 'https://api.n0v.top/api/v1/snapshots/snap_docs_01/entries?limit=1'"
          },
          {
            "lang": "curl",
            "label": "末页",
            "source": "curl -i -H \"Authorization: Bearer ${TOKEN}\" 'https://api.n0v.top/api/v1/snapshots/snap_docs_01/entries?limit=1&cursor=c_AQ'"
          }
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ]
      }
    },
    "/api/v1/seedance": {
      "post": {
        "operationId": "startVideoGeneration",
        "tags": [
          "视频生成"
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "summary": "创建生成任务并接收事件流",
        "description": "提交镜头描述后，服务在同一条 HTTP 连接中持续返回 `text/event-stream`，直到上游生成完成、失败或取消。所需权限为 `generation:write`。使用 `client_credentials` 取得的访问令牌，有效期 900 秒。以 `Authorization: Bearer <token>` 传递非空的不透明字符串，服务校验签发记录、到期时间及授权范围。\n\n`Idempotency-Key` 在任务活动期间及终态后 24 小时有效。服务先对 JSON 解析、补齐默认值，再比较同一键下的输入；重试同一请求复用原任务并重放事件。收到任务标识后，断线续接应使用事件读取接口和最近已处理的事件编号。\n\n编号事件的 `id` 为从 1 开始单调递增的十进制数。注释行 `: keep-alive` 是心跳，无事件编号。客户端按空行切分事件、合并 `data` 行；先处理 `generation.created`，随后接收 `progress`、`video.segment` 或 `agent.instruction`。\n\n`video.segment` 先发送序号 0 的 fMP4 初始化分片，再按序发送媒体分片。`delivery=links` 时按事件中的 `url` 下载；`delivery=inline` 时，每条分片事件另含 `data_base64`，解码得到相同的字节。SSE 始终传输 UTF-8 文本。\n\n`agent.instruction` 是界面提示。`show_progress` 更新百分比，`add_caption` 在指定毫秒区间展示纯文本字幕，`record_asset` 记录资产标识。客户端按 `instruction_id` 去重，忽略未知动作。\n\n一个任务只产生一个终态事件：`completed` 提供成品和资产标识，`failed` 包含错误码，`cancelled` 确认取消。发出终态事件后关闭流；响应头已发出时，失败通过事件报告，HTTP 状态码仍为 200。",
        "parameters": [
          {
            "$ref": "#/components/parameters/GenerationIdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerationCreate"
              },
              "example": {
                "prompt": "薄雾退去，镜头沿林间小径缓慢向前推进。",
                "negative_prompt": "文字、水印",
                "aspect_ratio": "16:9",
                "duration": 5,
                "delivery": "links"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "请求通过校验后，保持 SSE 连接直至任务终态。",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "complete": {
                    "summary": "从排队、分片到完成的整个事件流",
                    "value": "id: 1\nevent: generation.created\ndata: {\"generation_id\":\"gen_demo_001\",\"status\":\"queued\"}\n\n: keep-alive\n\nid: 2\nevent: progress\ndata: {\"generation_id\":\"gen_demo_001\",\"progress\":35}\n\nid: 3\nevent: agent.instruction\ndata: {\"generation_id\":\"gen_demo_001\",\"instruction_id\":\"ins_demo_001\",\"action\":\"show_progress\",\"arguments\":{\"percent\":35}}\n\nid: 4\nevent: video.segment\ndata: {\"generation_id\":\"gen_demo_001\",\"sequence\":0,\"kind\":\"init\",\"url\":\"/api/v1/generations/gen_demo_001/segments/0\",\"media_type\":\"video/mp4\"}\n\nid: 5\nevent: video.segment\ndata: {\"generation_id\":\"gen_demo_001\",\"sequence\":1,\"kind\":\"media\",\"url\":\"/api/v1/generations/gen_demo_001/segments/1\",\"media_type\":\"video/mp4\"}\n\nid: 6\nevent: completed\ndata: {\"generation_id\":\"gen_demo_001\",\"status\":\"completed\",\"progress\":100,\"asset_id\":\"ast_render_001\",\"video_url\":\"/api/v1/generations/gen_demo_001/video\"}\n\n"
                  },
                  "failed": {
                    "summary": "失败终止事件",
                    "value": "id: 6\nevent: failed\ndata: {\"generation_id\":\"gen_demo_001\",\"status\":\"failed\",\"error\":{\"code\":\"render_failed\",\"message\":\"上游未能完成渲染。\"}}\n\n"
                  },
                  "cancelled": {
                    "summary": "取消终止事件",
                    "value": "id: 6\nevent: cancelled\ndata: {\"generation_id\":\"gen_demo_001\",\"status\":\"cancelled\"}\n\n"
                  }
                }
              }
            },
            "x-event-schemas": {
              "generation.created": {
                "$ref": "#/components/schemas/GenerationCreatedEvent"
              },
              "progress": {
                "$ref": "#/components/schemas/GenerationProgressEvent"
              },
              "agent.instruction": {
                "$ref": "#/components/schemas/GenerationInstruction"
              },
              "video.segment": {
                "$ref": "#/components/schemas/GenerationSegmentEvent"
              },
              "completed": {
                "$ref": "#/components/schemas/GenerationCompletedEvent"
              },
              "failed": {
                "$ref": "#/components/schemas/GenerationFailedEvent"
              },
              "cancelled": {
                "$ref": "#/components/schemas/GenerationCancelledEvent"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/GenerationInvalid"
          },
          "401": {
            "$ref": "#/components/responses/GenerationUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/GenerationKeyConflict"
          },
          "422": {
            "$ref": "#/components/responses/GenerationValidation"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -N -sS -H \"Authorization: Bearer $STUDIO_TOKEN\" \\\n  -H 'Accept: text/event-stream' -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: catalog-shot-001' \\\n  --data '{\"prompt\":\"薄雾退去，镜头沿林间小径缓慢向前推进。\",\"negative_prompt\":\"文字、水印\",\"aspect_ratio\":\"16:9\",\"duration\":5,\"delivery\":\"links\"}' \\\n  https://api.n0v.top/api/v1/seedance"
          }
        ]
      }
    },
    "/api/v1/generations/{generation_id}": {
      "get": {
        "operationId": "getVideoGeneration",
        "tags": [
          "视频生成"
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "summary": "读取生成任务状态",
        "description": "`generation:read`。查询排队、生成或终态。`asset_id` 和 `video_url` 只在完成态出现；失败态通过 `error` 说明原因。",
        "parameters": [
          {
            "$ref": "#/components/parameters/GenerationId"
          }
        ],
        "responses": {
          "200": {
            "description": "示例中的任务已完成。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationState"
                },
                "example": {
                  "generation_id": "gen_demo_001",
                  "status": "completed",
                  "progress": 100,
                  "asset_id": "ast_render_001",
                  "video_url": "/api/v1/generations/gen_demo_001/video"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/GenerationUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/GenerationUnknown"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS -H \"Authorization: Bearer $STUDIO_TOKEN\" https://api.n0v.top/api/v1/generations/gen_demo_001"
          }
        ]
      }
    },
    "/api/v1/generations/{generation_id}/events": {
      "get": {
        "operationId": "replayVideoGenerationEvents",
        "tags": [
          "事件与视频"
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "summary": "重放并继续接收事件",
        "description": "`generation:read`。断线后携带该任务最后处理的 `Last-Event-ID`。已有记录从游标之后开始重放，若任务仍在运行，连接继续接收新事件。省略游标时从第一条记录开始。若游标已到终态，返回 204；若游标超出最新编号，返回 400。终态后的事件记录保留 24 小时。重连不会重新创建任务。\n\n若只需回看事件，以 `Accept: application/json` 读取最多 100 条已记录事件。可继续把最后处理的 id 放入 Last-Event-ID；没有新事件时列表为空。",
        "parameters": [
          {
            "$ref": "#/components/parameters/GenerationId"
          },
          {
            "$ref": "#/components/parameters/GenerationLastEventId"
          }
        ],
        "responses": {
          "200": {
            "description": "从给定游标之后重放事件，随后接收新事件直至终态。",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "replay": {
                    "summary": "Last-Event-ID: 4 时返回的后续事件",
                    "value": "id: 5\nevent: video.segment\ndata: {\"generation_id\":\"gen_demo_001\",\"sequence\":1,\"kind\":\"media\",\"url\":\"/api/v1/generations/gen_demo_001/segments/1\",\"media_type\":\"video/mp4\"}\n\nid: 6\nevent: completed\ndata: {\"generation_id\":\"gen_demo_001\",\"status\":\"completed\",\"progress\":100,\"asset_id\":\"ast_render_001\",\"video_url\":\"/api/v1/generations/gen_demo_001/video\"}\n\n"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "event",
                              "data"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "event": {
                                "type": "string",
                                "enum": [
                                  "generation.created"
                                ]
                              },
                              "data": {
                                "$ref": "#/components/schemas/GenerationCreatedEvent"
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "event",
                              "data"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "event": {
                                "type": "string",
                                "enum": [
                                  "progress"
                                ]
                              },
                              "data": {
                                "$ref": "#/components/schemas/GenerationProgressEvent"
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "event",
                              "data"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "event": {
                                "type": "string",
                                "enum": [
                                  "video.segment"
                                ]
                              },
                              "data": {
                                "$ref": "#/components/schemas/GenerationSegmentEvent"
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "event",
                              "data"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "event": {
                                "type": "string",
                                "enum": [
                                  "agent.instruction"
                                ]
                              },
                              "data": {
                                "$ref": "#/components/schemas/GenerationInstruction"
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "event",
                              "data"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "event": {
                                "type": "string",
                                "enum": [
                                  "completed"
                                ]
                              },
                              "data": {
                                "$ref": "#/components/schemas/GenerationCompletedEvent"
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "event",
                              "data"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "event": {
                                "type": "string",
                                "enum": [
                                  "failed"
                                ]
                              },
                              "data": {
                                "$ref": "#/components/schemas/GenerationFailedEvent"
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "event",
                              "data"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "minimum": 1
                              },
                              "event": {
                                "type": "string",
                                "enum": [
                                  "cancelled"
                                ]
                              },
                              "data": {
                                "$ref": "#/components/schemas/GenerationCancelledEvent"
                              }
                            }
                          }
                        ]
                      }
                    }
                  }
                },
                "example": {
                  "items": [
                    {
                      "id": 2,
                      "event": "progress",
                      "data": {
                        "generation_id": "gen_demo_001",
                        "progress": 35
                      }
                    }
                  ]
                }
              }
            },
            "x-event-schemas": {
              "generation.created": {
                "$ref": "#/components/schemas/GenerationCreatedEvent"
              },
              "progress": {
                "$ref": "#/components/schemas/GenerationProgressEvent"
              },
              "agent.instruction": {
                "$ref": "#/components/schemas/GenerationInstruction"
              },
              "video.segment": {
                "$ref": "#/components/schemas/GenerationSegmentEvent"
              },
              "completed": {
                "$ref": "#/components/schemas/GenerationCompletedEvent"
              },
              "failed": {
                "$ref": "#/components/schemas/GenerationFailedEvent"
              },
              "cancelled": {
                "$ref": "#/components/schemas/GenerationCancelledEvent"
              }
            }
          },
          "204": {
            "description": "指定游标已到达该任务的终态。响应无正文。"
          },
          "400": {
            "$ref": "#/components/responses/GenerationInvalid"
          },
          "401": {
            "$ref": "#/components/responses/GenerationUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/GenerationUnknown"
          },
          "410": {
            "$ref": "#/components/responses/GenerationExpired"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -N -sS -H \"Authorization: Bearer $STUDIO_TOKEN\" \\\n  -H 'Accept: text/event-stream' -H 'Last-Event-ID: 4' \\\n  https://api.n0v.top/api/v1/generations/gen_demo_001/events"
          }
        ]
      }
    },
    "/api/v1/generations/{generation_id}/cancel": {
      "post": {
        "operationId": "cancelVideoGeneration",
        "tags": [
          "视频生成"
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "summary": "取消生成任务",
        "description": "`generation:write`。取消排队或运行中的任务，返回确认后的状态，并向已有事件连接发送一次 `cancelled`。重复取消同一已取消任务仍返回已取消状态。对已经完成或失败的任务取消则返回 409。",
        "parameters": [
          {
            "$ref": "#/components/parameters/GenerationId"
          }
        ],
        "responses": {
          "200": {
            "description": "任务已取消。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationState"
                },
                "example": {
                  "generation_id": "gen_demo_001",
                  "status": "cancelled",
                  "progress": 35
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/GenerationUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/GenerationUnknown"
          },
          "409": {
            "$ref": "#/components/responses/GenerationNotReady"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -sS -X POST -H \"Authorization: Bearer $STUDIO_TOKEN\" https://api.n0v.top/api/v1/generations/gen_demo_001/cancel"
          }
        ]
      }
    },
    "/api/v1/generations/{generation_id}/video": {
      "get": {
        "operationId": "downloadGeneratedVideo",
        "tags": [
          "事件与视频"
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "summary": "下载成品 MP4",
        "description": "`generation:read`。任务完成后可下载完整视频，也可以用一个字节范围续传。部分响应的 `Content-Range` 使用包含两端的区间；范围起点越过文件末尾时返回 416。",
        "parameters": [
          {
            "$ref": "#/components/parameters/GenerationId"
          },
          {
            "name": "Range",
            "in": "header",
            "required": false,
            "description": "单段字节区间。例如 bytes=0-1023。",
            "schema": {
              "type": "string"
            },
            "example": "bytes=0-1023"
          }
        ],
        "responses": {
          "200": {
            "description": "完整 MP4。",
            "headers": {
              "Accept-Ranges": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "bytes"
                  ]
                },
                "description": "支持单段字节范围请求。"
              },
              "Content-Length": {
                "schema": {
                  "type": "integer",
                  "format": "int64"
                },
                "description": "本次响应实际传送的字节数。"
              }
            },
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "206": {
            "description": "指定区间内的 MP4 字节。",
            "headers": {
              "Accept-Ranges": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "bytes"
                  ]
                },
                "description": "支持单段字节范围请求。"
              },
              "Content-Length": {
                "schema": {
                  "type": "integer",
                  "format": "int64"
                },
                "description": "本次响应实际传送的字节数。"
              },
              "Content-Range": {
                "schema": {
                  "type": "string"
                },
                "description": "实际返回的起止字节和文件总字节数。"
              }
            },
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/GenerationUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/GenerationUnknown"
          },
          "409": {
            "$ref": "#/components/responses/GenerationNotReady"
          },
          "416": {
            "description": "所请求的范围不可满足。",
            "headers": {
              "Content-Range": {
                "description": "格式为 bytes */N，其中 N 为文件的总字节数。",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -fsS -H \"Authorization: Bearer $STUDIO_TOKEN\" --range 0-1023 \\\n  --output video.part https://api.n0v.top/api/v1/generations/gen_demo_001/video"
          }
        ]
      }
    },
    "/api/v1/generations/{generation_id}/segments/{sequence}": {
      "get": {
        "operationId": "downloadVideoSegment",
        "tags": [
          "事件与视频"
        ],
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "summary": "读取已发布的 fMP4 分片",
        "description": "`generation:read`。按 `video.segment` 事件中的链接读取单个分片。序号 0 是初始化分片，序号 1 起是媒体分片。分片发布后即可读取，无需等待整段视频完成；尚未发布的序号返回 404。",
        "parameters": [
          {
            "$ref": "#/components/parameters/GenerationId"
          },
          {
            "name": "sequence",
            "in": "path",
            "required": true,
            "description": "事件中的 sequence，0 为初始化分片。",
            "schema": {
              "type": "integer",
              "description": "分片序号；0 为初始化分片，媒体分片从 1 连续递增。",
              "minimum": 0
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "单个初始化或媒体分片的原始字节。",
            "headers": {
              "Content-Length": {
                "schema": {
                  "type": "integer",
                  "format": "int64"
                },
                "description": "本次响应实际传送的字节数。"
              }
            },
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/GenerationUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/GenerationUnknown"
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -fsS -H \"Authorization: Bearer $STUDIO_TOKEN\" --output segment-1.m4s \\\n  https://api.n0v.top/api/v1/generations/gen_demo_001/segments/1"
          }
        ]
      }
    },
    "/api/v1/assets": {
      "post": {
        "tags": [
          "素材管理"
        ],
        "summary": "导入小型图片素材",
        "description": "需要 `media:write` 权限。仅接受 JSON 中的标准 base64 字符串，解码后上限为 2 MiB（2,097,152 字节），允许 image/png、image/jpeg、image/webp，并核对文件签名与声明 MIME。不得附带 data URI 前缀或空白字符；不接受 URL，也不会向外部地址抓取素材。校验与保存完成后返回 201 和素材元数据，查询响应不回传原始 base64。",
        "operationId": "studioCreateAsset",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediaAssetImport"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "素材已保存，Location 指向素材元数据。",
            "headers": {
              "Location": {
                "description": "创建的素材路径。",
                "schema": {
                  "type": "string",
                  "example": "/api/v1/assets/ast_demo_001"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaAsset"
                }
              }
            }
          },
          "400": {
            "description": "base64 无效、为空或包含不支持的字段。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "INVALID_BASE64",
                  "message": "content_base64 必须是非空标准 base64。"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "description": "解码后的素材超过 2 MiB。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "ASSET_TOO_LARGE",
                  "message": "解码后的素材不得超过 2097152 字节。"
                }
              }
            }
          },
          "415": {
            "description": "MIME 不受支持，或文件签名与声明不一致。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "UNSUPPORTED_MEDIA_TYPE",
                  "message": "仅接受签名与声明一致的 PNG、JPEG 或 WebP 图片。"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "素材管理"
        ],
        "summary": "分页列出素材",
        "description": "需要 `media:read` 权限。按 created_at 降序、id 降序稳定排序。cursor 是不透明的快照游标；续页保持同一快照，首次查询之后新增的素材不会插入该分页序列。next_cursor 为 null 且 has_more 为 false 表示结束；无效或过期游标返回 400。结果仅含元数据，不含图片正文。",
        "operationId": "studioListAssets",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "本页最多返回的条目数。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "example": 20
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "原样使用上一页的 next_cursor；首次查询省略。",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            },
            "example": "cur_demo_assets_page_2"
          }
        ],
        "responses": {
          "200": {
            "description": "素材列表及下一页游标。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaAssetPage"
                }
              }
            }
          },
          "400": {
            "description": "分页参数或游标无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "INVALID_CURSOR",
                  "message": "该分页游标无效或已过期，请重新请求第一页。"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/assets/{asset_id}": {
      "get": {
        "tags": [
          "素材管理"
        ],
        "summary": "查询素材元数据",
        "description": "需要 `media:read` 权限。返回素材类型、解码后的字节数与内容 SHA-256，可用于核对导入内容；不返回 base64 或任意外部下载地址。",
        "operationId": "studioGetAsset",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "parameters": [
          {
            "name": "asset_id",
            "in": "path",
            "required": true,
            "description": "素材标识。",
            "schema": {
              "type": "string",
              "pattern": "^ast_[a-z0-9_]+$"
            },
            "example": "ast_demo_001"
          }
        ],
        "responses": {
          "200": {
            "description": "指定素材的元数据。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaAsset"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "素材不存在。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "ASSET_NOT_FOUND",
                  "message": "未找到该素材。"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/storyboards": {
      "post": {
        "tags": [
          "分镜编排"
        ],
        "summary": "保存连续分镜时间线",
        "description": "需要 `media:write` 权限。按 shots 顺序保存镜头。时间码使用 HH:MM:SS.mmm，起点包含、终点不包含；首镜头从零开始，每个镜头 start < end，后一镜头 start 必须等于前一镜头 end，末镜头 end 必须等于 total_duration_ms。总时长不超过 10 分钟，镜头编号从 1 连续递增；有空隙、重叠、时长不符或引用素材不存在时返回 422。此接口只保存编排，不触发视频渲染。",
        "operationId": "studioCreateStoryboard",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediaStoryboardCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "分镜已保存。",
            "headers": {
              "Location": {
                "description": "创建的分镜路径。",
                "schema": {
                  "type": "string",
                  "example": "/api/v1/storyboards/sb_demo_001"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaStoryboard"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "description": "分镜时间线或素材引用不满足约束。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "STORYBOARD_TIMELINE_INVALID",
                  "message": "镜头必须连续，且末镜头结束时间必须等于总时长。"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/storyboards/{storyboard_id}": {
      "get": {
        "tags": [
          "分镜编排"
        ],
        "summary": "读取完整分镜",
        "description": "需要 `media:read` 权限。返回已保存的完整镜头序列，保持创建时的顺序、时间码与总时长；不会自动补齐、重排或重新生成镜头。source_generation_id 仅用于关联生成任务。",
        "operationId": "studioGetStoryboard",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "parameters": [
          {
            "name": "storyboard_id",
            "in": "path",
            "required": true,
            "description": "分镜标识。",
            "schema": {
              "type": "string",
              "pattern": "^sb_[a-z0-9_]+$"
            },
            "example": "sb_demo_001"
          }
        ],
        "responses": {
          "200": {
            "description": "保存后的分镜及完整镜头列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaStoryboard"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "分镜不存在。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "STORYBOARD_NOT_FOUND",
                  "message": "未找到该分镜。"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/captions": {
      "post": {
        "tags": [
          "字幕轨道"
        ],
        "summary": "创建人工编排的字幕轨道",
        "description": "需要 `media:write` 权限。接收已编排的字幕文本与时间码，不执行语音识别。字幕编号从 1 连续递增，时间码使用 HH:MM:SS.mmm，每条 start < end 且不超过 total_duration_ms；按时间顺序提交，允许间隙，不允许重叠。text 为单行纯文本，不接受换行、<、>、& 或 WebVTT 标记；总时长不超过 10 分钟。",
        "operationId": "studioCreateCaption",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediaCaptionCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "字幕轨道已保存，可通过 track_path 读取 WebVTT。",
            "headers": {
              "Location": {
                "description": "创建的字幕元数据路径。",
                "schema": {
                  "type": "string",
                  "example": "/api/v1/captions/cap_demo_001"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaCaption"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "description": "字幕时间码、顺序、语言或文本不符合约束。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "CAPTION_TIMELINE_INVALID",
                  "message": "字幕时间段不得重叠或超出总时长。"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/captions/{caption_id}": {
      "get": {
        "tags": [
          "字幕轨道"
        ],
        "summary": "查询字幕文本与时间码",
        "description": "需要 `media:read` 权限。以 JSON 返回语言、来源任务、全部字幕条目和相对导出路径。track_path 对应同一份不可变字幕内容，适合编辑器预览；读取不会生成新版本。",
        "operationId": "studioGetCaption",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "parameters": [
          {
            "name": "caption_id",
            "in": "path",
            "required": true,
            "description": "字幕轨道标识。",
            "schema": {
              "type": "string",
              "pattern": "^cap_[a-z0-9_]+$"
            },
            "example": "cap_demo_001"
          }
        ],
        "responses": {
          "200": {
            "description": "字幕轨道的完整 JSON 表示。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaCaption"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "字幕轨道不存在。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "CAPTION_NOT_FOUND",
                  "message": "未找到该字幕轨道。"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/captions/{caption_id}/track.vtt": {
      "get": {
        "tags": [
          "字幕轨道"
        ],
        "summary": "导出 WebVTT 字幕文件",
        "description": "需要 `media:read` 权限。以 UTF-8 文本返回标准 WebVTT，使用 LF 换行，以 WEBVTT 文件头和空行开始；字幕编号、时间码及文本与 JSON 元数据一致。响应不是 JSON 包装，也不包含 BOM、样式块或远程资源引用。",
        "operationId": "studioGetCaptionVtt",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "parameters": [
          {
            "name": "caption_id",
            "in": "path",
            "required": true,
            "description": "字幕轨道标识。",
            "schema": {
              "type": "string",
              "pattern": "^cap_[a-z0-9_]+$"
            },
            "example": "cap_demo_001"
          }
        ],
        "responses": {
          "200": {
            "description": "可直接保存为 .vtt 文件的字幕正文。",
            "headers": {
              "Content-Disposition": {
                "description": "建议保存的字幕文件名。",
                "schema": {
                  "type": "string",
                  "example": "inline; filename=\"cap_demo_001.zh-CN.vtt\""
                }
              }
            },
            "content": {
              "text/vtt": {
                "schema": {
                  "type": "string"
                },
                "example": "WEBVTT\n\n1\n00:00:00.000 --> 00:00:02.500\n先确认画面中的主色与留白。\n\n2\n00:00:03.000 --> 00:00:06.000\n再用缓慢推进展示细节。\n\n"
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "字幕轨道不存在。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaProblem"
                },
                "example": {
                  "code": "CAPTION_NOT_FOUND",
                  "message": "未找到该字幕轨道。"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/token": {
      "post": {
        "tags": [
          "工作区鉴权"
        ],
        "operationId": "issueWorkspaceToken",
        "summary": "交换工作区令牌",
        "description": "以表单提交客户端凭据及用空格分隔的权限。服务端核对客户端所属工作区及权限范围。令牌有效期为 900 秒，过期后重新申请。",
        "security": [],
        "responses": {
          "200": {
            "description": "请求成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceAccess"
                },
                "example": {
                  "access_token": "example-token-value",
                  "token_type": "Bearer",
                  "expires_in": 900,
                  "scope": "generation:write generation:read"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "400": {
            "description": "请求格式或权限无效。"
          },
          "401": {
            "description": "客户端凭据无效。"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceCredentials"
              },
              "example": {
                "grant_type": "client_credentials",
                "client_id": "demo-studio",
                "client_secret": "example-only",
                "scope": "generation:write generation:read"
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/session": {
      "get": {
        "tags": [
          "工作区鉴权"
        ],
        "operationId": "getWorkspaceSession",
        "summary": "查看令牌会话",
        "description": "返回令牌的工作区、已授予权限及到期时刻。客户端可在生成前检查权限；响应省略令牌正文。",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "请求成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSession"
                },
                "example": {
                  "workspace_id": "ws_demo",
                  "client_id": "demo-studio",
                  "scopes": [
                    "generation:read",
                    "generation:write"
                  ],
                  "expires_at": "2026-01-15T08:15:00Z"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "401": {
            "description": "令牌已过期或无法识别。"
          }
        }
      }
    },
    "/api/v1/generations/{generation_id}/instructions": {
      "get": {
        "tags": [
          "Agent 指令与回执"
        ],
        "operationId": "listAgentInstructions",
        "summary": "读取任务指令收件箱",
        "description": "需要 `generation:read`。返回该工作区任务发出的有界客户端动作；同一指令再次出现在事件流时仍使用原 ID。按返回的游标翻页，末页的游标为 null。",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "请求成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstructionInbox"
                },
                "example": {
                  "items": [
                    {
                      "generation_id": "gen_demo_001",
                      "instruction_id": "ins_demo_001",
                      "action": "show_progress",
                      "arguments": {
                        "percent": 35
                      }
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "parameters": [
          {
            "name": "generation_id",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false
          }
        ]
      }
    },
    "/api/v1/generations/{generation_id}/instructions/{instruction_id}/ack": {
      "post": {
        "tags": [
          "Agent 指令与回执"
        ],
        "operationId": "ackAgentInstruction",
        "summary": "确认客户端指令",
        "description": "需要 `generation:write`。界面完成动作后提交 applied；用户跳过则提交 skipped。同一指令重复提交相同结果返回同一份回执，互相矛盾的回执返回 409。",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "请求成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstructionReceipt"
                },
                "example": {
                  "instruction_id": "ins_demo_001",
                  "status": "applied"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "已登记不同状态的回执。"
          }
        },
        "parameters": [
          {
            "name": "generation_id",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "instruction_id",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstructionReceiptInput"
              },
              "example": {
                "status": "applied"
              }
            }
          }
        }
      }
    },
    "/api/v1/deliveries": {
      "post": {
        "tags": [
          "交付与用量"
        ],
        "operationId": "createStudioDelivery",
        "summary": "建立成片交付记录",
        "description": "需要 `media:write`。成片完成后，将视频与同一任务的可选字幕登记为一份交付。未指定字幕时传 null；生成尚未完成时返回 409。",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "responses": {
          "201": {
            "description": "记录已创建。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryRecord"
                },
                "example": {
                  "delivery_id": "del_demo_001",
                  "generation_id": "gen_demo_001",
                  "video_href": "/api/v1/generations/gen_demo_001/video",
                  "caption_href": "/api/v1/captions/cap_demo_001/track.vtt"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "生成任务尚未产出成片。"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeliveryRequest"
              },
              "example": {
                "generation_id": "gen_demo_001",
                "caption_id": "cap_demo_001"
              }
            }
          }
        }
      }
    },
    "/api/v1/deliveries/{delivery_id}": {
      "get": {
        "tags": [
          "交付与用量"
        ],
        "operationId": "getStudioDelivery",
        "summary": "获取交付清单",
        "description": "需要 `media:read`。读取登记的资源路径；视频和字幕分别沿用其自身的访问权限及媒体类型。",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "请求成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryRecord"
                },
                "example": {
                  "delivery_id": "del_demo_001",
                  "generation_id": "gen_demo_001",
                  "video_href": "/api/v1/generations/gen_demo_001/video",
                  "caption_href": "/api/v1/captions/cap_demo_001/track.vtt"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "parameters": [
          {
            "name": "delivery_id",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ]
      }
    },
    "/api/v1/usage": {
      "get": {
        "tags": [
          "交付与用量"
        ],
        "operationId": "getStudioUsage",
        "summary": "查询单日用量",
        "description": "需要 `media:read`。按指定 UTC 自然日归集成功生成的任务数、成片总时长和内容传输字节数。重复拉取同一事件不增加生成时长。",
        "security": [
          {
            "StudioBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "请求成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceUsage"
                },
                "example": {
                  "date": "2026-01-15",
                  "completed_generations": 3,
                  "generated_seconds": 18,
                  "transferred_bytes": 7340032
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "required": true
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "SitePath": {
        "type": "string",
        "pattern": "^/",
        "description": "以本站域名为基准的绝对路径"
      },
      "Service": {
        "type": "object",
        "required": [
          "schema_version",
          "name",
          "documentation",
          "resources"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "example": "1.0",
            "description": "服务描述格式的版本。"
          },
          "name": {
            "type": "string",
            "example": "N0V 公共资源目录",
            "description": "服务中文名称。"
          },
          "documentation": {
            "$ref": "#/components/schemas/SitePath"
          },
          "resources": {
            "$ref": "#/components/schemas/SitePath"
          }
        }
      },
      "ResourceIndex": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Resource"
            },
            "description": "当前公开发布的 JSON 资源清单。"
          }
        }
      },
      "Resource": {
        "type": "object",
        "required": [
          "id",
          "title",
          "href",
          "media_type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "service",
            "description": "目录内唯一的条目标识。"
          },
          "title": {
            "type": "string",
            "example": "服务描述",
            "description": "用于显示的资源名称。"
          },
          "href": {
            "$ref": "#/components/schemas/SitePath"
          },
          "media_type": {
            "type": "string",
            "example": "application/json",
            "description": "读取资源时使用的媒体类型。"
          }
        }
      },
      "CreateSnapshot": {
        "type": "object",
        "required": [
          "resource_ids"
        ],
        "properties": {
          "resource_ids": {
            "type": "array",
            "description": "按传入顺序保存的公开资源标识，每项只出现一次。",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "service",
                "resources",
                "openapi"
              ]
            }
          }
        }
      },
      "Snapshot": {
        "type": "object",
        "required": [
          "snapshot_id",
          "resource_ids",
          "total"
        ],
        "properties": {
          "snapshot_id": {
            "type": "string",
            "example": "snap_docs_01"
          },
          "resource_ids": {
            "type": "array",
            "description": "按传入顺序保存的公开资源标识，每项只出现一次。",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "service",
                "resources",
                "openapi"
              ]
            }
          },
          "total": {
            "type": "integer",
            "minimum": 1,
            "description": "整份快照内的资源数量。"
          }
        }
      },
      "SnapshotPage": {
        "type": "object",
        "required": [
          "snapshot_id",
          "items",
          "total",
          "next_cursor"
        ],
        "properties": {
          "snapshot_id": {
            "type": "string",
            "example": "snap_docs_01"
          },
          "items": {
            "type": "array",
            "description": "仅含本页的条目，顺序与创建请求一致。",
            "items": {
              "$ref": "#/components/schemas/Resource"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 1,
            "description": "快照全部条目数，各页相同。"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "description": "下一页的不透明游标。末页返回 null。"
          }
        }
      },
      "GenerationCreate": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "镜头或画面描述。校验时忽略首尾空白，结果至少含一个非空白字符。",
            "minLength": 1,
            "maxLength": 2000
          },
          "negative_prompt": {
            "type": "string",
            "description": "希望画面避免的元素。",
            "maxLength": 1000
          },
          "aspect_ratio": {
            "type": "string",
            "enum": [
              "16:9",
              "9:16",
              "1:1"
            ],
            "default": "16:9"
          },
          "duration": {
            "type": "integer",
            "description": "输出时长，单位秒。",
            "minimum": 3,
            "maximum": 12,
            "default": 5
          },
          "delivery": {
            "type": "string",
            "enum": [
              "links",
              "inline"
            ],
            "default": "links",
            "description": "links 通过分片链接取回视频；inline 还在同一 SSE 连接的 video.segment 事件中传送字节。"
          }
        }
      },
      "GenerationState": {
        "type": "object",
        "required": [
          "generation_id",
          "status",
          "progress"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled"
            ]
          },
          "progress": {
            "type": "integer",
            "description": "已报告的整体进度百分比。只有完成态保证为 100。",
            "minimum": 0,
            "maximum": 100
          },
          "asset_id": {
            "type": "string",
            "description": "已完成视频的资产标识。",
            "example": "ast_render_001"
          },
          "video_url": {
            "type": "string",
            "description": "完成时返回的成品下载路径。"
          },
          "error": {
            "$ref": "#/components/schemas/GenerationError"
          }
        }
      },
      "GenerationError": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "稳定的错误标识。"
          },
          "message": {
            "type": "string",
            "description": "可显示给调用方的错误说明。"
          }
        }
      },
      "GenerationCreatedEvent": {
        "type": "object",
        "required": [
          "generation_id",
          "status"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued"
            ]
          }
        }
      },
      "GenerationProgressEvent": {
        "type": "object",
        "required": [
          "generation_id",
          "progress"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "progress": {
            "type": "integer",
            "description": "已完成百分比。",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "GenerationSegmentEvent": {
        "type": "object",
        "required": [
          "generation_id",
          "sequence",
          "kind",
          "url",
          "media_type"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "sequence": {
            "type": "integer",
            "description": "分片序号；0 为初始化分片，媒体分片从 1 连续递增。",
            "minimum": 0
          },
          "kind": {
            "type": "string",
            "enum": [
              "init",
              "media"
            ]
          },
          "url": {
            "type": "string",
            "description": "按序读取该分片的相对路径。"
          },
          "media_type": {
            "type": "string",
            "enum": [
              "video/mp4"
            ]
          },
          "data_base64": {
            "type": "string",
            "format": "byte",
            "description": "仅在 inline 模式中出现。使用标准 Base64 编码完整的单个初始化或媒体分片；解码后与 url 返回的字节一致。"
          }
        }
      },
      "GenerationShowProgress": {
        "type": "object",
        "required": [
          "generation_id",
          "instruction_id",
          "action",
          "arguments"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "instruction_id": {
            "type": "string",
            "description": "指令标识，重放时保持不变。",
            "example": "ins_demo_001"
          },
          "action": {
            "type": "string",
            "enum": [
              "show_progress"
            ]
          },
          "arguments": {
            "type": "object",
            "required": [
              "percent"
            ],
            "properties": {
              "percent": {
                "type": "integer",
                "description": "界面显示的百分比。",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        }
      },
      "GenerationAddCaption": {
        "type": "object",
        "required": [
          "generation_id",
          "instruction_id",
          "action",
          "arguments"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "instruction_id": {
            "type": "string",
            "description": "指令标识。"
          },
          "action": {
            "type": "string",
            "enum": [
              "add_caption"
            ]
          },
          "arguments": {
            "type": "object",
            "required": [
              "text",
              "start_ms",
              "end_ms"
            ],
            "properties": {
              "text": {
                "type": "string",
                "description": "作为普通文本展示的字幕。"
              },
              "start_ms": {
                "type": "integer",
                "description": "开始时间，以视频起点为基准的毫秒数。",
                "minimum": 0
              },
              "end_ms": {
                "type": "integer",
                "description": "终止时间，须大于开始时间，以毫秒计。",
                "minimum": 1
              }
            }
          }
        }
      },
      "GenerationRecordAsset": {
        "type": "object",
        "required": [
          "generation_id",
          "instruction_id",
          "action",
          "arguments"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "instruction_id": {
            "type": "string",
            "description": "指令标识。"
          },
          "action": {
            "type": "string",
            "enum": [
              "record_asset"
            ]
          },
          "arguments": {
            "type": "object",
            "required": [
              "asset_id"
            ],
            "properties": {
              "asset_id": {
                "type": "string",
                "description": "已完成视频的资产标识。",
                "example": "ast_render_001"
              }
            }
          }
        }
      },
      "GenerationInstruction": {
        "description": "客户端仅识别已列出的三种显示动作。未知动作应忽略；字幕按纯文本展示。",
        "oneOf": [
          {
            "$ref": "#/components/schemas/GenerationShowProgress"
          },
          {
            "$ref": "#/components/schemas/GenerationAddCaption"
          },
          {
            "$ref": "#/components/schemas/GenerationRecordAsset"
          }
        ],
        "discriminator": {
          "propertyName": "action",
          "mapping": {
            "show_progress": "#/components/schemas/GenerationShowProgress",
            "add_caption": "#/components/schemas/GenerationAddCaption",
            "record_asset": "#/components/schemas/GenerationRecordAsset"
          }
        }
      },
      "GenerationCompletedEvent": {
        "type": "object",
        "required": [
          "generation_id",
          "asset_id",
          "video_url",
          "progress",
          "status"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "asset_id": {
            "type": "string",
            "description": "已完成视频的资产标识。",
            "example": "ast_render_001"
          },
          "video_url": {
            "type": "string",
            "description": "成品 MP4 的相对地址。"
          },
          "progress": {
            "type": "integer",
            "enum": [
              100
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "completed"
            ]
          }
        }
      },
      "GenerationFailedEvent": {
        "type": "object",
        "required": [
          "generation_id",
          "status",
          "error"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "status": {
            "type": "string",
            "enum": [
              "failed"
            ]
          },
          "error": {
            "$ref": "#/components/schemas/GenerationError"
          }
        }
      },
      "GenerationCancelledEvent": {
        "type": "object",
        "required": [
          "generation_id",
          "status"
        ],
        "properties": {
          "generation_id": {
            "type": "string",
            "description": "任务标识。",
            "example": "gen_demo_001"
          },
          "status": {
            "type": "string",
            "enum": [
              "cancelled"
            ]
          }
        }
      },
      "MediaAssetImport": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "filename",
          "mime_type",
          "content_base64"
        ],
        "properties": {
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
            "description": "用于显示的文件名；仅允许 ASCII 字母、数字、点、下划线和连字符，不作为存储路径。"
          },
          "mime_type": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg",
              "image/webp"
            ]
          },
          "content_base64": {
            "type": "string",
            "minLength": 4,
            "maxLength": 2796204,
            "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
            "description": "标准 base64；上限按解码后的 2 MiB 检查，编码长度上限不能替代解码大小检查。"
          }
        },
        "example": {
          "filename": "palette-demo.png",
          "mime_type": "image/png",
          "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGMwTpv5HwAENAIyWy0K4AAAAABJRU5ErkJggg=="
        }
      },
      "MediaAsset": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "filename",
          "mime_type",
          "size_bytes",
          "sha256",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ast_[a-z0-9_]+$"
          },
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
          },
          "mime_type": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg",
              "image/webp"
            ]
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2097152,
            "description": "原始素材解码后的字节数。"
          },
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "原始解码内容的 SHA-256，不是 base64 文本的摘要。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "example": {
          "id": "ast_demo_001",
          "filename": "palette-demo.png",
          "mime_type": "image/png",
          "size_bytes": 70,
          "sha256": "1432c6765dea9d78715445ac73e83e158cfc3fce8e9d94db16228c933ef7440b",
          "created_at": "2026-11-19T09:00:00Z"
        }
      },
      "MediaAssetPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "next_cursor",
          "has_more"
        ],
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/MediaAsset"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 512,
            "description": "有后续页时返回不透明游标；末页固定为 null。"
          },
          "has_more": {
            "type": "boolean",
            "description": "仅当 next_cursor 非 null 时为 true。"
          }
        },
        "example": {
          "items": [
            {
              "id": "ast_demo_001",
              "filename": "palette-demo.png",
              "mime_type": "image/png",
              "size_bytes": 70,
              "sha256": "1432c6765dea9d78715445ac73e83e158cfc3fce8e9d94db16228c933ef7440b",
              "created_at": "2026-11-19T09:00:00Z"
            }
          ],
          "next_cursor": null,
          "has_more": false
        }
      },
      "MediaTimecode": {
        "type": "string",
        "pattern": "^[0-9]{2}:[0-5][0-9]:[0-5][0-9]\\.[0-9]{3}$",
        "description": "小时、分钟、秒与三位毫秒，固定格式 HH:MM:SS.mmm；不得超过所属时间线总时长。",
        "example": "00:00:03.000"
      },
      "MediaShot": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "index",
          "title",
          "asset_id",
          "start",
          "end"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "从 1 连续递增的镜头序号。"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "asset_id": {
            "type": "string",
            "pattern": "^ast_[a-z0-9_]+$"
          },
          "start": {
            "$ref": "#/components/schemas/MediaTimecode"
          },
          "end": {
            "$ref": "#/components/schemas/MediaTimecode"
          }
        },
        "example": {
          "index": 1,
          "title": "建立主色与留白",
          "asset_id": "ast_demo_001",
          "start": "00:00:00.000",
          "end": "00:00:03.000"
        }
      },
      "MediaStoryboardCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title",
          "source_generation_id",
          "total_duration_ms",
          "shots"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "source_generation_id": {
            "type": "string",
            "pattern": "^gen_[a-z0-9_]+$",
            "description": "关联的生成任务标识；不触发任务执行。"
          },
          "total_duration_ms": {
            "type": "integer",
            "minimum": 1,
            "maximum": 600000
          },
          "shots": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "description": "连续、无空隙且无重叠的镜头序列；末镜头结束时间必须等于 total_duration_ms。",
            "items": {
              "$ref": "#/components/schemas/MediaShot"
            }
          }
        },
        "example": {
          "title": "色彩卡片六秒演示",
          "source_generation_id": "gen_demo_001",
          "total_duration_ms": 6000,
          "shots": [
            {
              "index": 1,
              "title": "建立主色与留白",
              "asset_id": "ast_demo_001",
              "start": "00:00:00.000",
              "end": "00:00:03.000"
            },
            {
              "index": 2,
              "title": "缓慢推进到画面细节",
              "asset_id": "ast_demo_001",
              "start": "00:00:03.000",
              "end": "00:00:06.000"
            }
          ]
        }
      },
      "MediaStoryboard": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "title",
          "source_generation_id",
          "total_duration_ms",
          "shots",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^sb_[a-z0-9_]+$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "source_generation_id": {
            "type": "string",
            "pattern": "^gen_[a-z0-9_]+$"
          },
          "total_duration_ms": {
            "type": "integer",
            "minimum": 1,
            "maximum": 600000
          },
          "shots": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "description": "与创建请求相同的完整、连续时间线。",
            "items": {
              "$ref": "#/components/schemas/MediaShot"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "example": {
          "id": "sb_demo_001",
          "title": "色彩卡片六秒演示",
          "source_generation_id": "gen_demo_001",
          "total_duration_ms": 6000,
          "shots": [
            {
              "index": 1,
              "title": "建立主色与留白",
              "asset_id": "ast_demo_001",
              "start": "00:00:00.000",
              "end": "00:00:03.000"
            },
            {
              "index": 2,
              "title": "缓慢推进到画面细节",
              "asset_id": "ast_demo_001",
              "start": "00:00:03.000",
              "end": "00:00:06.000"
            }
          ],
          "created_at": "2026-11-19T09:01:00Z"
        }
      },
      "MediaCue": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "index",
          "start",
          "end",
          "text"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 1,
            "maximum": 300,
            "description": "从 1 连续递增；导出时用作 WebVTT cue 标识。"
          },
          "start": {
            "$ref": "#/components/schemas/MediaTimecode"
          },
          "end": {
            "$ref": "#/components/schemas/MediaTimecode"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^\\r\\n<>&]+$",
            "description": "单行纯文本，无换行、HTML 实体或 WebVTT 标记。"
          }
        },
        "example": {
          "index": 1,
          "start": "00:00:00.000",
          "end": "00:00:02.500",
          "text": "先确认画面中的主色与留白。"
        }
      },
      "MediaCaptionCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source_generation_id",
          "language",
          "total_duration_ms",
          "cues"
        ],
        "properties": {
          "source_generation_id": {
            "type": "string",
            "pattern": "^gen_[a-z0-9_]+$"
          },
          "language": {
            "type": "string",
            "enum": [
              "zh-CN",
              "en-US",
              "ja-JP"
            ],
            "description": "支持的 BCP 47 语言标签。"
          },
          "total_duration_ms": {
            "type": "integer",
            "minimum": 1,
            "maximum": 600000
          },
          "cues": {
            "type": "array",
            "minItems": 1,
            "maxItems": 300,
            "description": "按时间升序，允许间隙，不允许重叠，结束时间不得超过总时长。",
            "items": {
              "$ref": "#/components/schemas/MediaCue"
            }
          }
        },
        "example": {
          "source_generation_id": "gen_demo_001",
          "language": "zh-CN",
          "total_duration_ms": 6000,
          "cues": [
            {
              "index": 1,
              "start": "00:00:00.000",
              "end": "00:00:02.500",
              "text": "先确认画面中的主色与留白。"
            },
            {
              "index": 2,
              "start": "00:00:03.000",
              "end": "00:00:06.000",
              "text": "再用缓慢推进展示细节。"
            }
          ]
        }
      },
      "MediaCaption": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "source_generation_id",
          "language",
          "total_duration_ms",
          "cues",
          "track_path",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^cap_[a-z0-9_]+$"
          },
          "source_generation_id": {
            "type": "string",
            "pattern": "^gen_[a-z0-9_]+$"
          },
          "language": {
            "type": "string",
            "enum": [
              "zh-CN",
              "en-US",
              "ja-JP"
            ]
          },
          "total_duration_ms": {
            "type": "integer",
            "minimum": 1,
            "maximum": 600000
          },
          "cues": {
            "type": "array",
            "minItems": 1,
            "maxItems": 300,
            "description": "保存后的完整字幕条目，顺序与导出文件一致。",
            "items": {
              "$ref": "#/components/schemas/MediaCue"
            }
          },
          "track_path": {
            "type": "string",
            "pattern": "^/api/v1/captions/cap_[a-z0-9_]+/track\\.vtt$",
            "description": "同一字幕轨道的相对 WebVTT 导出路径。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "example": {
          "id": "cap_demo_001",
          "source_generation_id": "gen_demo_001",
          "language": "zh-CN",
          "total_duration_ms": 6000,
          "cues": [
            {
              "index": 1,
              "start": "00:00:00.000",
              "end": "00:00:02.500",
              "text": "先确认画面中的主色与留白。"
            },
            {
              "index": 2,
              "start": "00:00:03.000",
              "end": "00:00:06.000",
              "text": "再用缓慢推进展示细节。"
            }
          ],
          "track_path": "/api/v1/captions/cap_demo_001/track.vtt",
          "created_at": "2026-11-19T09:02:00Z"
        }
      },
      "MediaProblem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "INVALID_BASE64",
              "ASSET_TOO_LARGE",
              "UNSUPPORTED_MEDIA_TYPE",
              "INVALID_CURSOR",
              "ASSET_NOT_FOUND",
              "STORYBOARD_TIMELINE_INVALID",
              "STORYBOARD_NOT_FOUND",
              "CAPTION_TIMELINE_INVALID",
              "CAPTION_NOT_FOUND"
            ]
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "面向调用方的简短说明，不含内部路径或认证信息。"
          }
        },
        "example": {
          "code": "ASSET_NOT_FOUND",
          "message": "未找到该素材。"
        }
      },
      "WorkspaceCredentials": {
        "type": "object",
        "required": [
          "grant_type",
          "client_id",
          "client_secret",
          "scope"
        ],
        "properties": {
          "grant_type": {
            "type": "string",
            "enum": [
              "client_credentials"
            ]
          },
          "client_id": {
            "type": "string"
          },
          "client_secret": {
            "type": "string",
            "writeOnly": true
          },
          "scope": {
            "type": "string"
          }
        }
      },
      "WorkspaceAccess": {
        "type": "object",
        "required": [
          "access_token",
          "token_type",
          "expires_in",
          "scope"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "token_type": {
            "type": "string",
            "enum": [
              "Bearer"
            ]
          },
          "expires_in": {
            "type": "integer",
            "minimum": 1
          },
          "scope": {
            "type": "string"
          }
        }
      },
      "WorkspaceSession": {
        "type": "object",
        "required": [
          "workspace_id",
          "client_id",
          "scopes",
          "expires_at"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "client_id": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "generation:read",
                "generation:write",
                "media:read",
                "media:write"
              ]
            }
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "InstructionInbox": {
        "type": "object",
        "required": [
          "items",
          "next_cursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GenerationInstruction"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "InstructionReceiptInput": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "applied",
              "skipped"
            ]
          }
        }
      },
      "InstructionReceipt": {
        "type": "object",
        "required": [
          "instruction_id",
          "status"
        ],
        "properties": {
          "instruction_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "applied",
              "skipped"
            ]
          }
        }
      },
      "DeliveryRequest": {
        "type": "object",
        "required": [
          "generation_id",
          "caption_id"
        ],
        "properties": {
          "generation_id": {
            "type": "string"
          },
          "caption_id": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "DeliveryRecord": {
        "type": "object",
        "required": [
          "delivery_id",
          "generation_id",
          "video_href",
          "caption_href"
        ],
        "properties": {
          "delivery_id": {
            "type": "string"
          },
          "generation_id": {
            "type": "string"
          },
          "video_href": {
            "type": "string"
          },
          "caption_href": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "WorkspaceUsage": {
        "type": "object",
        "required": [
          "date",
          "completed_generations",
          "generated_seconds",
          "transferred_bytes"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "completed_generations": {
            "type": "integer",
            "minimum": 0
          },
          "generated_seconds": {
            "type": "number",
            "minimum": 0
          },
          "transferred_bytes": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    },
    "responses": {
      "HeadOK": {
        "description": "资源可读取。响应包含元数据，无正文。",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ETag"
          }
        }
      },
      "NotModified": {
        "description": "资源匹配请求中的实体标签。响应无正文，可复用已缓存的内容。",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ETag"
          }
        }
      },
      "Forbidden": {
        "description": "访问被拒绝。请核对 API 密钥、密钥权限及当前计划包含的功能。",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error",
                "code",
                "message",
                "detail"
              ],
              "additionalProperties": false,
              "properties": {
                "error": {
                  "type": "string",
                  "enum": [
                    "Forbidden"
                  ]
                },
                "code": {
                  "type": "string",
                  "enum": [
                    "AUTHENTICATION_NEEDED"
                  ]
                },
                "message": {
                  "type": "string",
                  "enum": [
                    "Authentication Needed"
                  ]
                },
                "detail": {
                  "type": "string",
                  "enum": [
                    "Check your API key, its permissions, and the features included in your plan."
                  ]
                }
              }
            },
            "example": {
              "error": "Forbidden",
              "code": "AUTHENTICATION_NEEDED",
              "message": "Authentication Needed",
              "detail": "Check your API key, its permissions, and the features included in your plan."
            }
          }
        }
      },
      "GenerationUnauthorized": {
        "description": "Bearer 缺失、格式不符、未知或已过期。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenerationError"
            },
            "example": {
              "code": "invalid_token",
              "message": "请重新取得有效的访问令牌。"
            }
          }
        },
        "headers": {
          "WWW-Authenticate": {
            "description": "Bearer 质询。",
            "schema": {
              "type": "string"
            },
            "example": "Bearer"
          }
        }
      },
      "GenerationInvalid": {
        "description": "请求 JSON、请求头或分页游标格式有误。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenerationError"
            },
            "example": {
              "code": "invalid_request",
              "message": "请求包含无法解析的字段或请求头。"
            }
          }
        }
      },
      "GenerationValidation": {
        "description": "请求体可解析，但字段值不满足字段约束。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenerationError"
            },
            "example": {
              "code": "invalid_parameters",
              "message": "请检查画面描述、时长或分片交付方式。"
            }
          }
        }
      },
      "GenerationUnknown": {
        "description": "任务或所请求的分片不存在，或任务不属于当前调用方。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenerationError"
            },
            "example": {
              "code": "not_found",
              "message": "未找到指定资源。"
            }
          }
        }
      },
      "GenerationExpired": {
        "description": "该任务的事件记录已超出重放保留时间。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenerationError"
            },
            "example": {
              "code": "replay_expired",
              "message": "事件记录已过期，请查询任务状态。"
            }
          }
        }
      },
      "GenerationKeyConflict": {
        "description": "同一调用方在有效期内将已有幂等键用于内容不同的请求。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenerationError"
            },
            "example": {
              "code": "idempotency_conflict",
              "message": "请为不同输入使用新的幂等键。"
            }
          }
        }
      },
      "GenerationNotReady": {
        "description": "请求与当前任务状态冲突。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenerationError"
            },
            "example": {
              "code": "invalid_state",
              "message": "当前任务状态不支持该操作。"
            }
          }
        }
      }
    },
    "headers": {
      "ETag": {
        "description": "当前资源的实体标签。复查相同资源时，在 If-None-Match 请求头中原样传回该值。",
        "schema": {
          "type": "string"
        }
      }
    },
    "parameters": {
      "IfNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "description": "填写上一次读取同一资源时收到的 ETag，包括引号。标签匹配时返回 304。",
        "schema": {
          "type": "string"
        }
      },
      "SnapshotId": {
        "name": "snapshot_id",
        "in": "path",
        "required": true,
        "description": "创建快照时返回的标识。",
        "schema": {
          "type": "string"
        },
        "example": "snap_docs_01"
      },
      "GenerationId": {
        "name": "generation_id",
        "in": "path",
        "required": true,
        "description": "创建操作通过 generation.created 事件返回的任务标识。",
        "schema": {
          "type": "string",
          "description": "任务标识。",
          "example": "gen_demo_001"
        },
        "example": "gen_demo_001"
      },
      "GenerationIdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "调用方创建的幂等键，作用域限于该调用方。相同键及相同参数返回已有任务的事件流；更改参数会触发冲突。",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "example": "catalog-shot-001"
      },
      "GenerationLastEventId": {
        "name": "Last-Event-ID",
        "in": "header",
        "required": false,
        "description": "已处理的最后一个事件编号。本次严格从它之后重放；首次读取可省略。游标按任务分别保存。",
        "schema": {
          "type": "string",
          "pattern": "^[0-9]+$"
        },
        "example": "4"
      }
    },
    "securitySchemes": {
      "StudioBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque",
        "description": "工作区短期令牌，通过 Authorization 请求头传递。"
      }
    }
  }
}
