Amend File Category (Multi-Image Crop)

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

Crop Category Correction: After automatic cropping, some child files have incorrect category recognition and need manual correction
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

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.ai/api/app-api/sip/platform/v2/file/amend_category"

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.ai/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))

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.ai/api/app-api/sip/platform/v2/file/fetch?workspace_id=<your-workspace-id>&file_id=<your-file-id>"

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.ai/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))

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.ai/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.ai/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

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

Overview

MCP&Skill

Workspace Management

Category Management

Upload

Parse

Classify

Split

Extract

Review

Delete Tasks

Retry Tasks

FAQ

Amend File Category (Multi-Image Crop)

Overview

Use Cases

API Endpoint

Request Parameters

crop_tasks Parameter Description

Parameter Description

Example Code

Get Parent Task ID and Child File Information

Response

Complete Example

Child Task ID Notes

Notes

​Overview

​Use Cases

​API Endpoint

​Request Parameters

​crop_tasks Parameter Description

​Parameter Description

​Example Code

​Get Parent Task ID and Child File Information

​Response

​Complete Example

​Child Task ID Notes

​Notes

Overview

Use Cases

API Endpoint

Request Parameters

crop_tasks Parameter Description

Parameter Description

Example Code

Get Parent Task ID and Child File Information

Response

Complete Example

Child Task ID Notes

Notes