Katechon Technology Reference Videos API

openapi: 3.2.0
info:
  title: Katechon Arc Reference Videos API
  description: Agent-powered AI video studio
  version: 1.0.0
tags:
- name: reference-videos
paths:
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/units:
    get:
      tags:
      - reference-videos
      summary: List Units
      operationId: list_units_api_v1_projects__project_name__reference_videos_episodes__episode__units_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Units Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - reference-videos
      summary: Add Unit
      operationId: add_unit_api_v1_projects__project_name__reference_videos_episodes__episode__units_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUnitRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Add Unit Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/units/{unit_id}:
    patch:
      tags:
      - reference-videos
      summary: Patch Unit
      operationId: patch_unit_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__patch
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      - name: unit_id
        in: path
        required: true
        schema:
          type: string
          title: Unit Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUnitRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Patch Unit Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units  Unit Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - reference-videos
      summary: Delete Unit
      operationId: delete_unit_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__delete
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      - name: unit_id
        in: path
        required: true
        schema:
          type: string
          title: Unit Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/units/reorder:
    post:
      tags:
      - reference-videos
      summary: Reorder Units
      operationId: reorder_units_api_v1_projects__project_name__reference_videos_episodes__episode__units_reorder_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Reorder Units Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units Reorder Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/units/{unit_id}/duration-precheck:
    get:
      tags:
      - reference-videos
      summary: Precheck Unit Duration
      description: '入队前的时长取档预检：申请秒数与请求时长基准不一致时前端需先向用户确认。


        ``needs_confirmation`` 为 false 时仅表示请求时长基准本身是当前档位成员。能力或档位元数据

        无法解析时返回结构化 blocker，不制造无约束申请。'
      operationId: precheck_unit_duration_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__duration_precheck_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      - name: unit_id
        in: path
        required: true
        schema:
          type: string
          title: Unit Id
      - name: narration_delivery
        in: query
        required: false
        schema:
          enum:
          - post_production
          - use_tts
          type: string
          default: post_production
          title: Narration Delivery
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Precheck Unit Duration Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units  Unit Id  Duration Precheck Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/script-preview:
    post:
      tags:
      - reference-videos
      summary: Preview Script
      description: '视频单元正文的读时派生预览：utterances + 降级可见性 warning。


        只读、不落盘——正文是唯一真相，utterances 与参考图都是机械派生物。声音相关的

        warning 依赖该集视频后端的能力（``voice_consistency`` 与参考音频段数上限）与本集的无声

        开关，与执行层同一份解析出口；能力解析失败时按 ``soft`` 降级，只是少发这几条提示。'
      operationId: preview_script_api_v1_projects__project_name__reference_videos_episodes__episode__script_preview_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScriptPreviewRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Preview Script Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Script Preview Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/units/{unit_id}/generate:
    post:
      tags:
      - reference-videos
      summary: Generate Unit
      operationId: generate_unit_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__generate_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      - name: unit_id
        in: path
        required: true
        schema:
          type: string
          title: Unit Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/GenerateUnitRequest'
              - type: 'null'
              title: Req
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Generate Unit Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units  Unit Id  Generate Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/units/generate-batch:
    post:
      tags:
      - reference-videos
      summary: Generate Units Batch
      description: 'Admit a whole batch of reference units, then create their tasks.


        The verdict is returned with HTTP 200 in all three outcomes: an evaluation

        that refuses the request is a successful evaluation, and collapsing it into a

        generic 4xx would hide every gap after the first one. Callers branch on

        ``decision``. An admitted batch whose enqueue is interrupted is likewise a

        200: the tasks already created run on, and ``enqueue_failures`` names the

        targets that never reached the queue.'
      operationId: generate_units_batch_api_v1_projects__project_name__reference_videos_episodes__episode__units_generate_batch_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateUnitsBatchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Generate Units Batch Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units Generate Batch Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_name}/reference-videos/episodes/{episode}/units/{unit_id}/upload-video:
    post:
      tags:
      - reference-videos
      summary: Upload Unit Video
      description: '上传单元成片视频，替换该 unit 的 AI 生成视频。


        复用生成链路的 finalize（抽缩略图、清旧 video_uri、status=completed），

        并纳入版本管理。参考图上传走既有的项目资产上传通路，不在此处。'
      operationId: upload_unit_video_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__upload_video_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: project_name
        in: path
        required: true
        schema:
          type: string
          title: Project Name
      - name: episode
        in: path
        required: true
        schema:
          type: integer
          title: Episode
      - name: unit_id
        in: path
        required: true
        schema:
          type: string
          title: Unit Id
      - name: X-Upload-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: X-Upload-Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_unit_video_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__upload_video_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Upload Unit Video Api V1 Projects  Project Name  Reference Videos Episodes  Episode  Units  Unit Id  Upload Video Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AddUnitRequest:
      properties:
        prompt:
          type: string
          title: Prompt
        duration_seconds:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Duration Seconds
        transition_to_next:
          type: string
          pattern: ^(cut|fade|dissolve)$
          title: Transition To Next
          default: cut
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
      additionalProperties: false
      type: object
      required:
      - prompt
      title: AddUnitRequest
    ? Body_upload_unit_video_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__upload_video_post
    : properties:
        file:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: File
      type: object
      title: Body_upload_unit_video_api_v1_projects__project_name__reference_videos_episodes__episode__units__unit_id__upload_video_post
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GenerateUnitRequest:
      properties:
        narration_delivery:
          type: string
          enum:
          - post_production
          - use_tts
          title: Narration Delivery
          default: post_production
        confirmed_request_duration_seconds:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Confirmed Request Duration Seconds
      type: object
      title: GenerateUnitRequest
    ReorderRequest:
      properties:
        unit_ids:
          items:
            type: string
          type: array
          title: Unit Ids
      type: object
      required:
      - unit_ids
      title: ReorderRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ScriptPreviewRequest:
      properties:
        prompt:
          type: string
          title: Prompt
          default: ''
      type: object
      title: ScriptPreviewRequest
    PatchUnitRequest:
      properties:
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
        duration_seconds:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Duration Seconds
        transition_to_next:
          anyOf:
          - type: string
            pattern: ^(cut|fade|dissolve)$
          - type: 'null'
          title: Transition To Next
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
      additionalProperties: false
      type: object
      title: PatchUnitRequest
    GenerateUnitsBatchRequest:
      properties:
        unit_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Unit Ids
        narration_delivery:
          type: string
          enum:
          - post_production
          - use_tts
          title: Narration Delivery
        confirmed_request_durations:
          additionalProperties:
            type: integer
            exclusiveMinimum: 0.0
          type: object
          title: Confirmed Request Durations
      type: object
      required:
      - narration_delivery
      title: GenerateUnitsBatchRequest
      description: '批量视频生成请求。


        ``unit_ids`` 省略时只补齐缺失项；指定 id 则重新生成对应单元。

        ``confirmed_request_durations`` 为用户在聚合确认中接受的时长档位。'
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/token