> ## Documentation Index
> Fetch the complete documentation index at: https://docs-claimagent.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 文件上传

> 文件上传。支持类型: jpg, jpeg, png, bmp, tiff, pdf。单文件上限: 50MB，单次上传上限: 20 个文件。



## OpenAPI

````yaml POST /doc-agent/api/v1/capability/file/upload
openapi: 3.0.3
info:
  description: |-
    CapabilityService 独立子能力服务
     提供文件上传、图像质检、材料分类、材料抽取等独立能力，不依赖案件流程。
     通过 batch_id 和 material_id 串联各能力调用。

     ## 典型调用流程
     1. 上传文件 → UploadFiles，获得 batch_id 和 material_id 列表
     2. (可选)图像质检 → CheckImageQuality，可独立调用，也可用上传返回的 material_id
     3. (可选)材料分类 → ClassifyMaterial，可独立调用，也可用上传返回的 material_id
     4. 材料抽取 → ExtractMaterial，传入 material_id 列表，返回每个材料的状态和结果
     5. 轮询 → 重复调用 ExtractMaterial 直到所有材料完成，或等待 callback_url 回调
     注: 质检和分类可独立调用，不依赖抽取流程；抽取接口的 material_ids 必须来自上传接口。
     注: ExtractMaterial 幂等，已完成的材料不会重新抽取，失败的材料会自动重试。

     ## 错误响应
     所有接口错误均返回 HTTP 非 200 状态码，body 格式: {"code": 400, "msg": "错误描述"}
     常见错误码:
       400 — 参数校验失败(缺少必填字段、文件数超限等)
       403 — 认证失败(x-ti-app-id 或 x-ti-secret-code 缺失/无效)
       404 — 资源不存在(material_id / batch_id 无效)
       500 — 内部处理异常

     错误响应示例:
       {"code": 404, "msg": "material not found"}
       {"code": 404, "msg": "batch not found"}
       {"code": 400, "msg": "material_ids or batch_id is required"}
       {"code": 400, "msg": "material does not belong to the specified batch"}
       {"code": 400, "msg": "files or file_urls is required"}
       {"code": 400, "msg": "所有材料必须属于同一批次"}
       {"code": 403, "msg": "x-api-key 或 x-ti-app-id/x-ti-secret-code 不能为空"}
  title: CapabilityService API
  version: 0.0.1
servers:
  - url: https://agents.textin.com/
security: []
tags:
  - name: CapabilityService
paths:
  /doc-agent/api/v1/capability/file/upload:
    post:
      tags:
        - CapabilityService
      description: '文件上传。支持类型: jpg, jpeg, png, bmp, tiff, pdf。单文件上限: 50MB，单次上传上限: 20 个文件。'
      operationId: CapabilityService_UploadFiles
      parameters:
        - in: header
          name: x-ti-app-id
          required: true
          schema:
            type: string
        - in: header
          name: x-ti-secret-code
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            example:
              batch_id: 661be601-65c7-4025-af0f-20d357dfb090
              files: '@门诊收费票据01.png'
            schema:
              properties:
                batch_id:
                  description: 调用方自定义批次ID(UUID格式，不传则系统生成)
                  example: 661be601-65c7-4025-af0f-20d357dfb090
                  type: string
                file_urls:
                  description: URL 上传(与 files 可混合使用)，JSON 数组格式
                  example: >-
                    ["https://example.com/file1.pdf","https://example.com/file2.jpg"]
                  type: string
                files:
                  description: 文件二进制上传(支持多文件)
                  format: binary
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                code: 200
                data:
                  batch_id: 661be601-65c7-4025-af0f-20d357dfb090
                  materials:
                    - file_name: 门诊收费票据01.png
                      file_size: '520464'
                      file_type: image/png
                      material_id: 8ffe03ce-4714-4b50-8daf-afee06002cc3
                    - file_name: 住院费用明细.jpg
                      file_size: '1814199'
                      file_type: image/jpeg
                      material_id: 27734e23-3482-42a3-98d7-1bdb369118bc
                message: OK
              schema:
                properties:
                  code:
                    description: 业务状态码
                    example: 200
                    type: integer
                  data:
                    $ref: >-
                      #/components/schemas/capability.v1.CapabilityUploadResponse
                  message:
                    description: 状态说明
                    example: OK
                    type: string
                type: object
          description: OK
components:
  schemas:
    capability.v1.CapabilityUploadResponse:
      properties:
        batch_id:
          description: 批次ID
          example: '"661be601-65c7-4025-af0f-20d357dfb090"'
          type: string
        materials:
          description: 上传结果列表
          items:
            $ref: '#/components/schemas/capability.v1.CapabilityMaterialInfo'
          type: array
      type: object
    capability.v1.CapabilityMaterialInfo:
      properties:
        file_name:
          description: 文件名
          type: string
        file_size:
          description: 文件大小 (bytes)
          type: string
        file_type:
          description: MIME 类型
          example: '"application/pdf"'
          type: string
        material_id:
          description: 材料唯一标识
          example: '"8ffe03ce-4714-4b50-8daf-afee06002cc3"'
          type: string
      type: object

````