openapi.yaml

openapi: "3.0.0"
info:
  title: "AI Agent Support Service API"
  description: "一个用于PDF处理和版面解析的API服务。"
  version: "1.0.0"
servers:
  - url: "http://localhost:8000"
    description: "开发服务器"
paths:
  /api/v1/process-pdf/:
    post:
      tags:
        - "PDF处理"
      summary: "处理PDF文件并返回图片URL"
      description: "上传一个PDF文件和DPI值，将其转换为图片，并返回图片的URL。"
      operationId: "processPdf"
      requestBody:
        description: "需要上传的PDF文件和DPI设置"
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: "要处理的PDF文件。"
                dpi:
                  type: integer
                  format: int32
                  description: "输出图像的DPI（每英寸点数）。"
                  default: 300
      responses:
        '200':
          description: "PDF处理成功"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "PDF processed successfully"
                  image_urls:
                    type: array
                    items:
                      type: string
                      format: url
                      example: "http://localhost:8000/static/your_file_1.png"
        '400':
          description: "无效的输入"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "服务器内部错误"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/process-pdf-files/:
    post:
      tags:
        - "PDF处理"
      summary: "处理PDF文件并直接返回图片文件"
      description: "上传一个PDF文件和DPI值，将其转换为图片，并以multipart/form-data格式直接返回图片文件。"
      operationId: "processPdfFiles"
      requestBody:
        description: "需要上传的PDF文件和DPI设置"
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: "要处理的PDF文件。"
                dpi:
                  type: integer
                  format: int32
                  description: "输出图像的DPI（每英寸点数）。"
                  default: 300
      responses:
        '200':
          description: "PDF处理成功，返回各个图片文件的下载链接"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "PDF processed successfully"
                  file_urls:
                    type: array
                    items:
                      type: string
                      format: url
                      example: "http://localhost:8000/api/v1/get-image/document_page_1.png"
                  total_files:
                    type: integer
                    example: 3
        '400':
          description: "无效的输入"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "服务器内部错误"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/get-image/{filename}:
    get:
      tags:
        - "PDF处理"
      summary: "下载指定的图片文件"
      description: "通过文件名下载转换后的图片文件。"
      operationId: "getImageFile"
      parameters:
        - name: filename
          in: path
          required: true
          description: "要下载的图片文件名"
          schema:
            type: string
            example: "document_page_1.png"
      responses:
        '200':
          description: "成功返回图片文件"
          content:
            image/png:
              schema:
                type: string
                format: binary
                description: "PNG格式的图片文件"
        '404':
          description: "图片文件未找到"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/process-pdf-stitched/:
    post:
      tags:
        - "PDF处理"
      summary: "处理PDF文件并返回拼接长图URL"
      description: "上传一个PDF文件和DPI值，将其转换为图片，按照现有规则进行旋转，然后以最大宽度为基准将图片上下拼接成一张长图，并返回图片URL。"
      operationId: "processPdfStitched"
      requestBody:
        description: "需要上传的PDF文件和DPI设置"
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: "要处理的PDF文件。"
                dpi:
                  type: integer
                  format: int32
                  description: "输出图像的DPI（每英寸点数）。"
                  default: 300
      responses:
        '200':
          description: "PDF处理成功，已生成拼接长图"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "PDF处理成功，已生成拼接长图"
                  stitched_image_url:
                    type: string
                    format: url
                    example: "http://localhost:8000/static/document_stitched.png"
                  filename:
                    type: string
                    example: "document_stitched.png"
        '400':
          description: "无效的输入"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "服务器内部错误"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/process-pdf-stitched-file/:
    post:
      tags:
        - "PDF处理"
      summary: "处理PDF文件并直接返回拼接长图文件"
      description: "上传一个PDF文件和DPI值，将其转换为图片，按照现有规则进行旋转，然后以最大宽度为基准将图片上下拼接成一张长图，直接返回文件。"
      operationId: "processPdfStitchedFile"
      requestBody:
        description: "需要上传的PDF文件和DPI设置"
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: "要处理的PDF文件。"
                dpi:
                  type: integer
                  format: int32
                  description: "输出图像的DPI（每英寸点数）。"
                  default: 300
      responses:
        '200':
          description: "成功返回拼接后的长图文件"
          content:
            image/png:
              schema:
                type: string
                format: binary
                description: "PNG格式的拼接长图文件"
        '400':
          description: "无效的输入"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "服务器内部错误"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/layout-parsing/:
    post:
      tags:
        - "版面解析"
      summary: "版面解析（JSON请求方式）"
      description: |
        接收图像/PDF的URL或Base64编码内容，返回版面解析结果（Markdown格式）。
        
        **自动处理机制**：
        - 如果传入URL，服务会自动下载内容并转换为Base64后再调用远程API
        - 如果URL指向本地static目录（如 /static/xxx.png），会直接从文件系统读取，避免网络请求
        - file_type 会根据URL后缀自动推断（.pdf → 0，其他 → 1）
      operationId: "layoutParsing"
      requestBody:
        description: "版面解析请求参数"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutParsingRequest'
      responses:
        '200':
          description: "版面解析成功"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutParsingResponse'
        '400':
          description: "无效的输入"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "服务器内部错误"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/layout-parsing/upload/:
    post:
      tags:
        - "版面解析"
      summary: "版面解析（文件上传方式）"
      description: |
        上传图像或PDF文件，将内容转换为Base64编码后调用版面解析API。
        
        **处理流程**：
        1. 接收上传的文件
        2. 将文件内容转换为Base64编码
        3. 调用远程版面解析API
        4. 返回Markdown解析结果
        
        文件不会保存到服务器，直接在内存中处理。
      operationId: "layoutParsingUpload"
      requestBody:
        description: "需要上传的文件和解析参数"
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: "要解析的图像或PDF文件。支持的类型：PDF、JPEG、PNG、GIF、WebP、BMP、TIFF"
                api_url:
                  type: string
                  description: "版面解析API服务地址（可选，默认从环境变量读取）"
                file_type:
                  type: integer
                  description: "文件类型。0表示PDF文件，1表示图像文件。若不提供则根据文件MIME类型自动推断。"
                  enum: [0, 1]
                visualize:
                  type: boolean
                  description: "是否返回可视化结果图"
                  default: false
                prettify_markdown:
                  type: boolean
                  description: "是否美化Markdown输出"
                  default: true
                use_layout_detection:
                  type: boolean
                  description: "是否使用版面检测"
                use_chart_recognition:
                  type: boolean
                  description: "是否使用图表识别"
                merge_layout_blocks:
                  type: boolean
                  description: "是否合并版面块"
      responses:
        '200':
          description: "版面解析成功"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "版面解析成功"
                  log_id:
                    type: string
                    description: "请求UUID"
                    example: "550e8400-e29b-41d4-a716-446655440000"
                  markdown_results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MarkdownResult'
                  data_info:
                    type: object
                    description: "输入数据信息"
                    properties:
                      width:
                        type: integer
                        example: 2481
                      height:
                        type: integer
                        example: 3508
                      type:
                        type: string
                        example: "image"
                  full_markdown:
                    type: string
                    description: "完整的Markdown文本"
        '400':
          description: "无效的输入"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "服务器内部错误"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/layout-parsing/markdown-only/:
    post:
      tags:
        - "版面解析"
      summary: "版面解析 - 仅返回Markdown"
      description: |
        简化版接口，只返回提取的Markdown文本内容，不包含详细的结构信息。
        
        **自动处理机制**：
        - 如果传入URL，服务会自动下载内容并转换为Base64后再调用远程API
        - 如果URL指向本地static目录（如 /static/xxx.png），会直接从文件系统读取，避免网络请求
        - file_type 会根据URL后缀自动推断（.pdf → 0，其他 → 1）
      operationId: "layoutParsingMarkdownOnly"
      requestBody:
        description: "版面解析请求参数"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutParsingRequest'
      responses:
        '200':
          description: "版面解析成功"
          content:
            application/json:
              schema:
                type: object
                properties:
                  log_id:
                    type: string
                    description: "请求UUID"
                    example: "550e8400-e29b-41d4-a716-446655440000"
                  full_markdown:
                    type: string
                    description: "完整的Markdown文本"
                  page_markdowns:
                    type: array
                    description: "按页的Markdown内容"
                    items:
                      type: object
                      properties:
                        page_index:
                          type: integer
                          description: "页码索引"
                          example: 0
                        markdown:
                          type: string
                          description: "该页的Markdown内容"
                  total_pages:
                    type: integer
                    description: "总页数"
                    example: 1
        '400':
          description: "无效的输入"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: "服务器内部错误"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          example: "错误详情"
    LayoutParsingRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          description: "服务器可访问的图像文件或PDF文件的URL，或文件内容的Base64编码结果。默认对于超过10页的PDF文件，只有前10页会被处理。"
          example: "http://example.com/document.png"
        api_url:
          type: string
          description: "版面解析API服务地址（可选，默认从环境变量LAYOUT_PARSING_API_URL读取）"
        file_type:
          type: integer
          description: "文件类型。0表示PDF文件，1表示图像文件。若不提供则根据URL自动推断文件类型。"
          enum: [0, 1]
        visualize:
          type: boolean
          description: "是否返回可视化结果图"
          default: false
        prettify_markdown:
          type: boolean
          description: "是否美化Markdown输出"
          default: true
        use_layout_detection:
          type: boolean
          description: "是否使用版面检测"
        use_chart_recognition:
          type: boolean
          description: "是否使用图表识别"
        merge_layout_blocks:
          type: boolean
          description: "是否合并版面块"
    LayoutParsingResponse:
      type: object
      properties:
        log_id:
          type: string
          description: "请求UUID"
          example: "550e8400-e29b-41d4-a716-446655440000"
        markdown_results:
          type: array
          description: "每页的Markdown结果"
          items:
            $ref: '#/components/schemas/MarkdownResult'
        data_info:
          type: object
          description: "输入数据信息"
          properties:
            width:
              type: integer
              example: 2481
            height:
              type: integer
              example: 3508
            type:
              type: string
              example: "image"
        full_markdown:
          type: string
          description: "完整的Markdown文本"
    MarkdownResult:
      type: object
      properties:
        text:
          type: string
          description: "Markdown文本"
        is_start:
          type: boolean
          description: "当前页第一个元素是否为段开始"
          default: true
        is_end:
          type: boolean
          description: "当前页最后一个元素是否为段结束"
          default: true