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

# 创建文件类别

> 在指定空间中创建一个新的文件类别，需要上传至少一个样本文件并配置至少一个字段。

支持一站式创建：可同时传入 `tables` 参数，创建表格及表格内嵌字段。




## OpenAPI

````yaml /docflow/cn/rest-api/openapi.bundle.yaml post /api/app-api/sip/platform/v2/category/create
openapi: 3.0.0
info:
  title: DocFlow API
  description: DocFlow REST API，提供文件上传和获取文件处理结果能力
  version: 2.8.4
servers:
  - url: https://docflow.textin.com
security:
  - ApiId: []
    SecretCode: []
paths:
  /api/app-api/sip/platform/v2/category/create:
    post:
      tags:
        - 文件类别
      summary: 创建文件类别
      description: |
        在指定空间中创建一个新的文件类别，需要上传至少一个样本文件并配置至少一个字段。

        支持一站式创建：可同时传入 `tables` 参数，创建表格及表格内嵌字段。
      operationId: createCategory
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                workspace_id:
                  type: string
                  description: 空间ID
                  example: '1234567890'
                name:
                  type: string
                  description: 文件类别名称
                  example: 发票
                  maxLength: 50
                category_prompt:
                  type: string
                  description: 用于分类的提示词
                  example: 增值税发票，包含发票代码、发票号码等字段
                  maxLength: 150
                description:
                  type: string
                  description: 文件类别描述
                extract_model:
                  type: string
                  description: |
                    抽取模型
                    - Auto: 智能匹配抽取模型
                    - Acgpt: 速度快，抽取结果稳定
                    - Acgpt-VL: 多模态，适用简单抽取（≤10 页）
                    - DF-M1: 适用复杂文档理解
                  example: Acgpt
                  enum:
                    - Auto
                    - Acgpt
                    - Acgpt-VL
                    - DF-M1
                sample_files:
                  type: array
                  description: 样本文件列表，至少上传一个样本文件，一个类别最多有20个样本文件
                  items:
                    type: string
                    format: binary
                  minItems: 1
                  maxItems: 10
                fields:
                  type: array
                  description: 字段配置列表，至少配置一个字段
                  items:
                    $ref: '#/components/schemas/CategoryFieldConfig'
                  minItems: 1
                tables:
                  type: array
                  description: 选填，表格配置列表（一站式创建），支持内嵌 fields
                  items:
                    $ref: '#/components/schemas/CategoryTableConfig'
                with_detail:
                  type: boolean
                  description: |
                    是否返回完整详情。传 true 时响应包含完整的分类信息（含字段、表格、样本）。
                    不传或为 false 时仅返回 category_id。
              required:
                - workspace_id
                - name
                - extract_model
                - sample_files
                - fields
      responses:
        '200':
          description: 成功创建文件类别
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeMessage'
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          category_id:
                            type: string
                            description: 文件类别ID
                            example: '1234567890'
                          name:
                            type: string
                            description: 文件类别名称（with_detail=true 时返回）
                          description:
                            type: string
                            description: 文件类别描述（with_detail=true 时返回）
                          category_prompt:
                            type: string
                            description: 分类提示词（with_detail=true 时返回）
                          extract_model:
                            type: string
                            description: 抽取模型（with_detail=true 时返回）
                          enabled:
                            type: integer
                            description: 启用状态（with_detail=true 时返回）
                          fields:
                            type: array
                            description: 字段列表（with_detail=true 时返回）
                            items:
                              $ref: '#/components/schemas/CategoryField'
                          tables:
                            type: array
                            description: 表格列表（with_detail=true 时返回）
                            items:
                              $ref: '#/components/schemas/CategoryTable'
                          samples:
                            type: array
                            description: 样本列表（with_detail=true 时返回）
                            items:
                              $ref: '#/components/schemas/CategorySample'
                        required:
                          - category_id
components:
  schemas:
    CategoryFieldConfig:
      type: object
      properties:
        name:
          type: string
          description: 字段名称
          example: 发票代码
        description:
          type: string
          description: 字段描述
          example: 发票代码描述
        prompt:
          type: string
          description: 语义抽取提示词
        use_prompt:
          type: boolean
          description: 是否使用语义提示词
        alias:
          type: array
          description: 字段别名。更新时：不传=不修改，传空数组[]=清空别名，传非空数组=覆盖
          items:
            type: string
          example:
            - 发票号
            - 票号
            - Invoice No.
        identity:
          type: string
          description: 导出字段名。更新时：不传=不修改，传空字符串""=清空，传非空值=覆盖
          example: invoice_number
        multi_value:
          type: boolean
          description: 是否多值抽取
        duplicate_value_distinct:
          type: boolean
          description: 是否重复值去重，仅当 multi_value 为 true 时有效
        transform_settings:
          $ref: '#/components/schemas/TransformSettings'
    CategoryTableConfig:
      type: object
      description: 一站式创建时的表格配置（含内嵌字段）
      properties:
        name:
          type: string
          description: 表格名称
          example: 明细表
          maxLength: 50
        prompt:
          type: string
          description: 表格语义抽取提示词
          maxLength: 200
        collect_from_multi_table:
          type: boolean
          description: 多表合并
        extract_model:
          type: string
          description: 表格级抽取模型
          enum:
            - Auto
            - Acgpt
            - Acgpt-VL
            - DF-M1
        fields:
          type: array
          description: 表格内嵌字段列表
          items:
            $ref: '#/components/schemas/CategoryFieldConfig'
      required:
        - name
    CodeMessage:
      type: object
      properties:
        code:
          type: integer
          description: 状态码
          example: 200
        msg:
          type: string
          description: 状态描述
      required:
        - code
        - msg
    CategoryField:
      allOf:
        - $ref: '#/components/schemas/CategoryFieldConfig'
        - type: object
          properties:
            id:
              type: string
              description: 字段ID
              example: '1234567890'
            enabled:
              $ref: '#/components/schemas/EnabledStatus'
            extract_model:
              type: string
              description: |
                字段抽取模型
                - Auto: 智能匹配抽取模型
                - Acgpt: 速度快，抽取结果稳定
                - Acgpt-VL: 多模态，适用简单抽取（≤10 页）
                - DF-M1: 适用复杂文档理解
                - 表格字段取所属表格的模型，普通字段取字段级配置；历史数据按分类配置推断
              example: Acgpt
    CategoryTable:
      type: object
      properties:
        id:
          type: string
          description: 表格ID
          example: '1234567890'
        name:
          type: string
          description: 表格名称
          example: 表格1
        description:
          type: string
          description: 表格描述
          example: 表格描述
        prompt:
          type: string
          description: 表格语义抽取提示词
          example: 请抽取每行的品名、数量和金额
        collect_from_multi_table:
          type: boolean
          description: 多表合并
          example: true
        extract_model:
          type: string
          description: 表格级抽取模型（Auto/Acgpt/Acgpt-VL/DF-M1）
          example: Acgpt
        fields:
          type: array
          items:
            $ref: '#/components/schemas/CategoryField'
    CategorySample:
      type: object
      description: 文件类别样本
      properties:
        sample_id:
          type: string
          description: 样本ID
          example: '1234567890'
        file_name:
          type: string
          description: 文件名
          example: invoice_sample.pdf
      required:
        - sample_id
        - file_name
    TransformSettings:
      type: object
      description: 字段输出转换配置，对抽取结果进行格式化处理后再输出。
      properties:
        type:
          type: string
          description: |
            转换类型，决定使用哪种转换规则：
            - `datetime`：将抽取结果标准化为指定日期格式
            - `enumerate`：限定抽取结果必须是预设枚举值之一
            - `regex`：用正则表达式对抽取结果进行匹配和替换
          enum:
            - datetime
            - enumerate
            - regex
        datetime_settings:
          type: object
          description: 时间格式化配置，type=datetime 时必填
          properties:
            format:
              type: string
              description: 目标日期格式，抽取结果将被标准化为此格式输出
              example: yyyy-MM-dd
        enumerate_settings:
          type: object
          description: 枚举限定配置，type=enumerate 时必填
          properties:
            items:
              type: array
              description: 允许的枚举值列表。抽取结果不在列表中时，按 mismatch_action 处理
              items:
                type: string
              example:
                - 增值税专用发票
                - 增值税普通发票
                - 电子发票
        regex_settings:
          type: object
          description: 正则转换配置，type=regex 时必填
          properties:
            match:
              type: string
              description: 匹配正则表达式，用于校验或捕获抽取结果
              example: ^(\d{4})-(\d{2})-(\d{2})$
            replace:
              type: string
              description: 替换表达式，支持 $1、$2 等捕获组引用
              example: $1/$2/$3
        mismatch_action:
          type: object
          description: 抽取结果不匹配转换规则时的处理方式（适用于所有转换类型，选填）
          properties:
            mode:
              type: string
              description: |
                处理模式：
                - `default`：输出指定的默认值（需配合 default_value）
                - `warning`：保留原始抽取结果，仅标记告警提醒人工复核
              enum:
                - default
                - warning
            default_value:
              type: string
              description: mode=default 时输出的默认值
              example: N/A
    EnabledStatus:
      type: integer
      description: |
        启用状态
        - 0: 禁用
        - 1: 启用
        - 2: 草稿
      enum:
        - 0
        - 1
        - 2
  securitySchemes:
    ApiId:
      type: apiKey
      in: header
      name: x-ti-app-id
    SecretCode:
      type: apiKey
      in: header
      name: x-ti-secret-code

````