Skip to main content

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

​
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

ParameterTypeRequiredDescription
workspace_idstringYesWorkspace ID
task_idstringYesParent task ID (multi-image crop task ID)
crop_tasksarrayYesMulti-image crop task list, each element contains crop_child_task_id and category

​
crop_tasks Parameter Description

ParameterTypeRequiredDescription
crop_child_task_idstringYesMulti-image crop child task ID
categorystringYesChild 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

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"

​
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: 
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>"

​
Response

After successfully modifying the file category, the API returns a success response: 
{
  "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
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