> ## 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.

# 修改文件类别（多图切分）

> 对于多图切分任务，使用 修改文件类别 接口修改切分后的文件类别

## 功能概述

对于已经处理完成的多图切分任务，如果发现切分后的子文件类别不正确，可以使用 修改文件类别 接口修改切分后的文件类别。

<Tip>
  此接口用于修改多图切分任务（`task_type = 2`，父任务）产生的子文件的类别。需要先获取父任务的 `task_id` 和子任务的 `crop_child_task_id`。
</Tip>

## 使用场景

1. **切分类别修正**：自动切分后，某些子文件的类别识别错误，需要手动修正
2. **类别调整**：业务需求变更，需要将切分后的文件重新分类

## API 接口

**接口地址**：`POST /api/app-api/sip/platform/v2/file/amend_category`

## 请求参数

| 参数名            | 类型     | 必填 | 说明                                                |
| -------------- | ------ | -- | ------------------------------------------------- |
| `workspace_id` | string | 是  | 空间ID                                              |
| `task_id`      | string | 是  | 父任务ID（多图切分任务的ID）                                  |
| `crop_tasks`   | array  | 是  | 多图切分任务列表，每个元素包含 `crop_child_task_id` 和 `category` |

### crop\_tasks 参数说明

| 参数名                  | 类型     | 必填 | 说明        |
| -------------------- | ------ | -- | --------- |
| `crop_child_task_id` | string | 是  | 多图切分子任务ID |
| `category`           | string | 是  | 子任务文件类别   |

### 参数说明

* `task_id`：父任务的ID（`task_type = 2`），可以通过 `file/fetch` 接口获取
* `crop_child_task_id`：子任务的ID（`task_type = 3`），可以从 `child_files` 中获取
* `category`：新文件类别名称，必须是已在 DocFlow 空间配置过的文件类别

## 示例代码

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "1234567890",
      "task_id": "1234567890",
      "crop_tasks": [
        {
          "crop_child_task_id": "1981692246135111680",
          "category": "电子发票（普通发票）"
        },
        {
          "crop_child_task_id": "1981692246135111681",
          "category": "火车票"
        }
      ]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/file/amend_category"
  ```

  ```python Python icon=python expandable theme={null}
  import requests
  import json

  def amend_crop_category(workspace_id, task_id, crop_tasks, app_id, secret_code):
      """
      修改多图切分任务的子文件类别
      
      Args:
          workspace_id: 空间ID
          task_id: 父任务ID（多图切分任务的ID）
          crop_tasks: 切分任务列表，格式为：
              [
                  {
                      "crop_child_task_id": "子任务ID",
                      "category": "类别名称"
                  },
                  ...
              ]
          app_id: 应用ID
          secret_code: 密钥
      """
      url = "https://docflow.textin.com/api/app-api/sip/platform/v2/file/amend_category"
      
      headers = {
          "x-ti-app-id": app_id,
          "x-ti-secret-code": secret_code,
          "Content-Type": "application/json"
      }
      
      payload = {
          "workspace_id": workspace_id,
          "task_id": task_id,
          "crop_tasks": crop_tasks
      }
      
      response = requests.post(url, headers=headers, json=payload)
      return response.json()

  # 使用示例
  if __name__ == "__main__":
      WORKSPACE_ID = "1234567890"
      PARENT_TASK_ID = "1234567890"  # 父任务ID（task_type = 2）
      APP_ID = "<your-app-id>"
      SECRET_CODE = "<your-secret-code>"
      
      # 定义切分任务：修改不同子文件的类别
      crop_tasks = [
          {
              "crop_child_task_id": "1981692246135111680",  # 子任务ID
              "category": "电子发票（普通发票）"
          },
          {
              "crop_child_task_id": "1981692246135111681",
              "category": "火车票"
          }
      ]
      
      result = amend_crop_category(WORKSPACE_ID, PARENT_TASK_ID, crop_tasks, APP_ID, SECRET_CODE)
      print(json.dumps(result, indent=2, ensure_ascii=False))
  ```
</CodeGroup>

## 获取父任务ID和子文件信息

在修改文件类别之前，需要先获取父任务的 `task_id` 和子文件的 `crop_child_task_id`。可以通过 `file/fetch` 接口查询：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/file/fetch?workspace_id=<your-workspace-id>&file_id=<your-file-id>"
  ```

  ```python Python icon=python expandable theme={null}
  import requests
  import json

  def get_crop_task_info(workspace_id, file_id, app_id, secret_code):
      """
      获取多图切分任务的信息，包括父任务ID和子文件信息
      """
      url = "https://docflow.textin.com/api/app-api/sip/platform/v2/file/fetch"
      
      headers = {
          "x-ti-app-id": app_id,
          "x-ti-secret-code": secret_code
      }
      
      params = {
          "workspace_id": workspace_id,
          "file_id": file_id
      }
      
      response = requests.get(url, headers=headers, params=params)
      data = response.json()
      
      files = data.get("result", {}).get("files", [])
      if files:
          file_data = files[0]
          task_id = file_data.get("task_id")
          task_type = file_data.get("task_type")
          child_files = file_data.get("child_files", [])
          
          # 提取子文件信息
          crop_children = []
          for child in child_files:
              if child.get("task_type") == 3:  # 多图切分产生的子文件
                  crop_children.append({
                      "crop_child_task_id": child.get("task_id"),
                      "category": child.get("category"),
                      "name": child.get("name"),
                      "from_parent_position_list": child.get("from_parent_position_list", []),
                      "crop_info": child.get("crop_info", {})
                  })
          
          return {
              "parent_task_id": task_id,
              "parent_task_type": task_type,
              "crop_children": crop_children
          }
      return None

  # 使用示例
  WORKSPACE_ID = "1234567890"
  FILE_ID = "202412190001"
  APP_ID = "<your-app-id>"
  SECRET_CODE = "<your-secret-code>"

  task_info = get_crop_task_info(WORKSPACE_ID, FILE_ID, APP_ID, SECRET_CODE)
  if task_info:
      print("父任务ID:", task_info["parent_task_id"])
      print("父任务类型:", task_info["parent_task_type"])
      print("子文件信息:")
      for child in task_info["crop_children"]:
          print(json.dumps(child, indent=2, ensure_ascii=False))
  ```
</CodeGroup>

## 返回结果

成功修改文件类别后，接口会返回成功响应：

```json expandable theme={null}
{
  "code": 200,
  "msg": "success"
}
```

## 完整示例

以下是一个完整的示例，展示如何查询多图切分任务信息，然后修改子文件的类别：

```python Python icon=python expandable theme={null}
import requests
import json

def get_crop_task_info(workspace_id, file_id, app_id, secret_code):
    """获取多图切分任务信息"""
    url = "https://docflow.textin.com/api/app-api/sip/platform/v2/file/fetch"
    headers = {
        "x-ti-app-id": app_id,
        "x-ti-secret-code": secret_code
    }
    params = {"workspace_id": workspace_id, "file_id": file_id}
    response = requests.get(url, headers=headers, params=params)
    return response.json()

def amend_crop_category(workspace_id, task_id, crop_tasks, app_id, secret_code):
    """修改多图切分任务的类别"""
    url = "https://docflow.textin.com/api/app-api/sip/platform/v2/file/amend_category"
    headers = {
        "x-ti-app-id": app_id,
        "x-ti-secret-code": secret_code,
        "Content-Type": "application/json"
    }
    payload = {
        "workspace_id": workspace_id,
        "task_id": task_id,
        "crop_tasks": crop_tasks
    }
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# 使用示例
WORKSPACE_ID = "1234567890"
FILE_ID = "202412190001"
APP_ID = "<your-app-id>"
SECRET_CODE = "<your-secret-code>"

# 1. 获取多图切分任务信息
file_info = get_crop_task_info(WORKSPACE_ID, FILE_ID, APP_ID, SECRET_CODE)
files = file_info.get("result", {}).get("files", [])
if files:
    file_data = files[0]
    parent_task_id = file_data.get("task_id")
    task_type = file_data.get("task_type")
    child_files = file_data.get("child_files", [])
    
    # 确认是多图切分父任务（task_type = 2）
    if task_type == 2:
        print(f"父任务ID: {parent_task_id}")
        print("当前子文件信息:")
        
        # 构建 crop_tasks 参数
        crop_tasks = []
        for child in child_files:
            if child.get("task_type") == 3:  # 多图切分产生的子文件
                crop_child_task_id = child.get("task_id")
                current_category = child.get("category")
                child_name = child.get("name")
                
                print(f"  - 子任务ID: {crop_child_task_id}")
                print(f"    文件名: {child_name}")
                print(f"    当前类别: {current_category}")
                
                # 示例：修改所有子文件的类别
                # 这里可以根据实际需求修改，例如根据文件名或其他条件判断
                crop_tasks.append({
                    "crop_child_task_id": crop_child_task_id,
                    "category": "电子发票（普通发票）"  # 新的类别，可以根据实际需求修改
                })
        
        # 2. 修改文件类别
        if crop_tasks:
            result = amend_crop_category(WORKSPACE_ID, parent_task_id, crop_tasks, APP_ID, SECRET_CODE)
            print(f"修改结果: {json.dumps(result, indent=2, ensure_ascii=False)}")
    else:
        print(f"该任务不是多图切分父任务（task_type={task_type}）")
```

## 子任务ID说明

* `crop_child_task_id` 是子任务的 `task_id`，可以从 `file/fetch` 接口返回的 `child_files` 中获取
* 每个多图切分产生的子文件都有唯一的 `task_id`
* 子文件的 `task_type` 为 `3`，表示多图切分产生的子文件

## 注意事项

1. **任务类型限制**：只有多图切分父任务（`task_type = 2`）才支持使用 `crop_tasks` 参数
2. **类别必须存在**：指定的 `category` 必须在 DocFlow 空间中已经配置过，否则会返回错误
3. **类别名称匹配**：类别名称必须与配置时完全一致（区分大小写）
4. **子任务ID必须有效**：确保 `crop_child_task_id` 是有效的子任务ID
5. **修改后重新处理**：修改文件类别后，系统会根据新的类别重新进行数据处理