{
  "openapi": "3.1.0",
  "info": {
    "title": "视频字幕与中文翻译 API",
    "description": "提交本地视频路径或上传文件，立即返回任务 ID；轮询任务后读取结构化原文与逐段中文，或下载字幕。任务与阶段结果保存在本机。",
    "version": "1.0.0"
  },
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "运行状态"
        ],
        "summary": "Health",
        "operationId": "health_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/api/v1/config": {
      "get": {
        "tags": [
          "运行状态"
        ],
        "summary": "Config",
        "operationId": "config_api_v1_config_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {}
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/videos": {
      "get": {
        "tags": [
          "视频"
        ],
        "summary": "Videos",
        "operationId": "videos_api_v1_videos_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {}
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/jobs": {
      "post": {
        "tags": [
          "字幕任务"
        ],
        "summary": "提交本地视频路径",
        "operationId": "create_job_api_v1_jobs_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PathJobRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "字幕任务"
        ],
        "summary": "List Jobs",
        "operationId": "list_jobs_api_v1_jobs_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 200,
              "minimum": 1,
              "default": 50,
              "title": "Limit"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "title": "Offset"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/JobView"
                  },
                  "title": "Response List Jobs Api V1 Jobs Get"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/upload": {
      "post": {
        "tags": [
          "字幕任务"
        ],
        "summary": "上传视频并创建任务",
        "operationId": "upload_job_api_v1_jobs_upload_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_upload_job_api_v1_jobs_upload_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/jobs/{job_id}": {
      "get": {
        "tags": [
          "字幕任务"
        ],
        "summary": "Get Job",
        "operationId": "get_job_api_v1_jobs__job_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/result": {
      "get": {
        "tags": [
          "任务结果"
        ],
        "summary": "Get Result",
        "operationId": "get_result_api_v1_jobs__job_id__result_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/TranscriptResult"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/files/{filename}": {
      "get": {
        "tags": [
          "任务结果"
        ],
        "summary": "Download",
        "operationId": "download_api_v1_jobs__job_id__files__filename__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Filename"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/cancel": {
      "post": {
        "tags": [
          "字幕任务"
        ],
        "summary": "Cancel",
        "operationId": "cancel_api_v1_jobs__job_id__cancel_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/retry": {
      "post": {
        "tags": [
          "字幕任务"
        ],
        "summary": "Retry",
        "operationId": "retry_api_v1_jobs__job_id__retry_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetryRequest",
                "default": {}
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Body_upload_job_api_v1_jobs_upload_post": {
        "properties": {
          "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "File",
            "description": "视频/音频文件"
          },
          "options": {
            "type": "string",
            "title": "Options",
            "description": "JobOptions 的 JSON 字符串，例如 {\"translate\":false}",
            "default": "{}"
          }
        },
        "type": "object",
        "required": [
          "file"
        ],
        "title": "Body_upload_job_api_v1_jobs_upload_post"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "JobOptions": {
        "properties": {
          "language": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 12
              },
              {
                "type": "null"
              }
            ],
            "title": "Language",
            "description": "原音语言代码，例如 en、zh；null 自动识别。"
          },
          "translate": {
            "type": "boolean",
            "title": "Translate",
            "description": "逐段翻译为简体中文；false 仅识别原文。",
            "default": true
          },
          "paragraph_max_chars": {
            "type": "integer",
            "maximum": 2000.0,
            "minimum": 80.0,
            "title": "Paragraph Max Chars",
            "default": 600
          },
          "paragraph_max_seconds": {
            "type": "number",
            "maximum": 180.0,
            "minimum": 5.0,
            "title": "Paragraph Max Seconds",
            "default": 45
          },
          "paragraph_pause_seconds": {
            "type": "number",
            "maximum": 10.0,
            "minimum": 0.2,
            "title": "Paragraph Pause Seconds",
            "default": 1.2
          },
          "preview_seconds": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 600.0,
                "minimum": 5.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Preview Seconds",
            "description": "只处理视频开头指定秒数，便于试跑；null 处理完整视频。"
          },
          "initial_prompt": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ],
            "title": "Initial Prompt",
            "description": "可选专有名词提示，帮助识别。"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "JobOptions"
      },
      "JobView": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed",
              "cancelled"
            ],
            "title": "Status"
          },
          "stage": {
            "type": "string",
            "title": "Stage"
          },
          "progress": {
            "type": "number",
            "title": "Progress"
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "title": "Updated At"
          },
          "filename": {
            "type": "string",
            "title": "Filename"
          },
          "options": {
            "$ref": "#/components/schemas/JobOptions"
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Language"
          },
          "duration": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Duration"
          },
          "paragraph_count": {
            "type": "integer",
            "title": "Paragraph Count",
            "default": 0
          },
          "translated_count": {
            "type": "integer",
            "title": "Translated Count",
            "default": 0
          },
          "cancel_requested": {
            "type": "boolean",
            "title": "Cancel Requested",
            "default": false
          },
          "error": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          },
          "files": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object",
            "title": "Files"
          },
          "status_url": {
            "type": "string",
            "title": "Status Url"
          },
          "result_url": {
            "type": "string",
            "title": "Result Url"
          }
        },
        "type": "object",
        "required": [
          "id",
          "status",
          "stage",
          "progress",
          "created_at",
          "updated_at",
          "filename",
          "options",
          "status_url",
          "result_url"
        ],
        "title": "JobView"
      },
      "Paragraph": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id"
          },
          "start": {
            "type": "number",
            "title": "Start"
          },
          "end": {
            "type": "number",
            "title": "End"
          },
          "segment_ids": {
            "items": {
              "type": "integer"
            },
            "type": "array",
            "title": "Segment Ids"
          },
          "source": {
            "type": "string",
            "title": "Source"
          },
          "translation": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Translation"
          }
        },
        "type": "object",
        "required": [
          "id",
          "start",
          "end",
          "segment_ids",
          "source"
        ],
        "title": "Paragraph"
      },
      "PathJobRequest": {
        "properties": {
          "language": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 12
              },
              {
                "type": "null"
              }
            ],
            "title": "Language",
            "description": "原音语言代码，例如 en、zh；null 自动识别。"
          },
          "translate": {
            "type": "boolean",
            "title": "Translate",
            "description": "逐段翻译为简体中文；false 仅识别原文。",
            "default": true
          },
          "paragraph_max_chars": {
            "type": "integer",
            "maximum": 2000.0,
            "minimum": 80.0,
            "title": "Paragraph Max Chars",
            "default": 600
          },
          "paragraph_max_seconds": {
            "type": "number",
            "maximum": 180.0,
            "minimum": 5.0,
            "title": "Paragraph Max Seconds",
            "default": 45
          },
          "paragraph_pause_seconds": {
            "type": "number",
            "maximum": 10.0,
            "minimum": 0.2,
            "title": "Paragraph Pause Seconds",
            "default": 1.2
          },
          "preview_seconds": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 600.0,
                "minimum": 5.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Preview Seconds",
            "description": "只处理视频开头指定秒数，便于试跑；null 处理完整视频。"
          },
          "initial_prompt": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ],
            "title": "Initial Prompt",
            "description": "可选专有名词提示，帮助识别。"
          },
          "video_path": {
            "type": "string",
            "maxLength": 4096,
            "minLength": 1,
            "title": "Video Path",
            "description": "服务端本地绝对路径，或相对于 VIDEO_ROOT 的文件名。"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "video_path"
        ],
        "title": "PathJobRequest"
      },
      "RetryRequest": {
        "properties": {
          "translate": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Translate",
            "description": "可将仅提取的任务设为 true，复用已识别原文补做翻译。"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "title": "RetryRequest"
      },
      "Segment": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id"
          },
          "start": {
            "type": "number",
            "minimum": 0.0,
            "title": "Start"
          },
          "end": {
            "type": "number",
            "minimum": 0.0,
            "title": "End"
          },
          "text": {
            "type": "string",
            "title": "Text"
          }
        },
        "type": "object",
        "required": [
          "id",
          "start",
          "end",
          "text"
        ],
        "title": "Segment"
      },
      "TranscriptResult": {
        "properties": {
          "language": {
            "type": "string",
            "title": "Language"
          },
          "duration": {
            "type": "number",
            "title": "Duration"
          },
          "segments": {
            "items": {
              "$ref": "#/components/schemas/Segment"
            },
            "type": "array",
            "title": "Segments"
          },
          "paragraphs": {
            "items": {
              "$ref": "#/components/schemas/Paragraph"
            },
            "type": "array",
            "title": "Paragraphs"
          },
          "translation_complete": {
            "type": "boolean",
            "title": "Translation Complete"
          },
          "subtitle_timing": {
            "type": "string",
            "title": "Subtitle Timing",
            "default": "中文和双语字幕使用段落起止时间；原文字幕保留识别片段时间。"
          }
        },
        "type": "object",
        "required": [
          "language",
          "duration",
          "segments",
          "paragraphs",
          "translation_complete"
        ],
        "title": "TranscriptResult"
      },
      "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"
      }
    },
    "securitySchemes": {
      "HTTPBearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}