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

# Amend File Category (Multi-Image Crop)

> For multi-image crop tasks, use the amend category API to modify the category of cropped files

## Overview

For completed multi-image crop tasks, if the category of cropped child files is incorrect, you can use the **amend category** API to modify the category of cropped files.

<Tip>
  This API is used to modify the category of child files generated by multi-image crop tasks (`task_type = 2`, parent task). You need to first obtain the parent task's `task_id` and child task's `crop_child_task_id`.
</Tip>

## Use Cases

1. **Crop Category Correction**: After automatic cropping, some child files have incorrect category recognition and need manual correction
2. **Category Adjustment**: Business requirements change and cropped files need to be reclassified

## API Endpoint

**Endpoint**: `POST /api/app-api/sip/platform/v2/file/amend_category`

## Request Parameters

| Parameter      | Type   | Required | Description                                                                           |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `workspace_id` | string | Yes      | Workspace ID                                                                          |
| `task_id`      | string | Yes      | Parent task ID (multi-image crop task ID)                                             |
| `crop_tasks`   | array  | Yes      | Multi-image crop task list, each element contains `crop_child_task_id` and `category` |

### crop\_tasks Parameter Description

| Parameter            | Type   | Required | Description                    |
| -------------------- | ------ | -------- | ------------------------------ |
| `crop_child_task_id` | string | Yes      | Multi-image crop child task ID |
| `category`           | string | Yes      | Child task file category       |

### Parameter Description

* `task_id`: Parent task ID (`task_type = 2`), can be obtained through the `file/fetch` API
* `crop_child_task_id`: Child task ID (`task_type = 3`), can be obtained from `child_files`
* `category`: New file category name, must be a file category already configured in the DocFlow workspace

## Example Code

<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": "Electronic Invoice (Regular)"
        },
        {
          "crop_child_task_id": "1981692246135111681",
          "category": "Train Ticket"
        }
      ]
    }' \
    "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):
      """
      Amend category for multi-image crop tasks
      
      Args:
          workspace_id: Workspace ID
          task_id: Parent task ID (multi-image crop task ID)
          crop_tasks: Crop task list, format:
              [
                  {
                      "crop_child_task_id": "Child task ID",
                      "category": "Category name"
                  },
                  ...
              ]
          app_id: Application ID
          secret_code: 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()

  # Usage example
  if __name__ == "__main__":
      WORKSPACE_ID = "1234567890"
      PARENT_TASK_ID = "1234567890"  # Parent task ID (task_type = 2)
      APP_ID = "<your-app-id>"
      SECRET_CODE = "<your-secret-code>"
      
      # Define crop tasks: modify category for different child files
      crop_tasks = [
          {
              "crop_child_task_id": "1981692246135111680",  # Child task ID
              "category": "Electronic Invoice (Regular)"
          },
          {
              "crop_child_task_id": "1981692246135111681",
              "category": "Train Ticket"
          }
      ]
      
      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>

## Get Parent Task ID and Child File Information

Before modifying the file category, you need to obtain the parent task's `task_id` and child file's `crop_child_task_id`. You can query it through the `file/fetch` API:

<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):
      """
      Get multi-image crop task information, including parent task ID and child file information
      """
      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", [])
          
          # Extract child file information
          crop_children = []
          for child in child_files:
              if child.get("task_type") == 3:  # Child files generated by multi-image crop
                  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

  # Usage example
  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("Parent task ID:", task_info["parent_task_id"])
      print("Parent task type:", task_info["parent_task_type"])
      print("Child file information:")
      for child in task_info["crop_children"]:
          print(json.dumps(child, indent=2, ensure_ascii=False))
  ```
</CodeGroup>

## Response

After successfully modifying the file category, the API returns a success response:

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

## Complete Example

The following is a complete example showing how to query multi-image crop task information and then modify child file categories:

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

def get_crop_task_info(workspace_id, file_id, app_id, secret_code):
    """Get multi-image crop task information"""
    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):
    """Amend category for multi-image crop tasks"""
    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()

# Usage example
WORKSPACE_ID = "1234567890"
FILE_ID = "202412190001"
APP_ID = "<your-app-id>"
SECRET_CODE = "<your-secret-code>"

# 1. Get multi-image crop task information
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", [])
    
    # Confirm it's a multi-image crop parent task (task_type = 2)
    if task_type == 2:
        print(f"Parent task ID: {parent_task_id}")
        print("Current child file information:")
        
        # Build crop_tasks parameter
        crop_tasks = []
        for child in child_files:
            if child.get("task_type") == 3:  # Child files generated by multi-image crop
                crop_child_task_id = child.get("task_id")
                current_category = child.get("category")
                child_name = child.get("name")
                
                print(f"  - Child task ID: {crop_child_task_id}")
                print(f"    File name: {child_name}")
                print(f"    Current category: {current_category}")
                
                # Example: Modify category for all child files
                # You can modify this based on actual requirements, such as judging by file name or other conditions
                crop_tasks.append({
                    "crop_child_task_id": crop_child_task_id,
                    "category": "Electronic Invoice (Regular)"  # New category, can be modified based on actual requirements
                })
        
        # 2. Amend file category
        if crop_tasks:
            result = amend_crop_category(WORKSPACE_ID, parent_task_id, crop_tasks, APP_ID, SECRET_CODE)
            print(f"Amendment result: {json.dumps(result, indent=2, ensure_ascii=False)}")
    else:
        print(f"This task is not a multi-image crop parent task (task_type={task_type})")
```

## Child Task ID Notes

* `crop_child_task_id` is the child task's `task_id`, which can be obtained from the `child_files` returned by the `file/fetch` API
* Each child file generated by multi-image crop has a unique `task_id`
* Child files have `task_type` of `3`, indicating they are generated by multi-image crop

## Notes

1. **Task Type Restriction**: Only multi-image crop parent tasks (`task_type = 2`) support using the `crop_tasks` parameter
2. **Category Must Exist**: The specified `category` must already be configured in the DocFlow workspace, otherwise an error will be returned
3. **Category Name Matching**: Category names must exactly match the configuration (case-sensitive)
4. **Child Task ID Must Be Valid**: Ensure `crop_child_task_id` is a valid child task ID
5. **Reprocessing After Modification**: After modifying the file category, the system will reprocess data according to the new category