Textin File Converter Pro

Convert documents between PDF, Word, Excel, PPT, and image formats using the Textin API. High-accuracy OCR-based conversion with layout preservation. Supports both single file and batch folder conversion. Use when the user needs to convert files between office document formats or between documents and images.

Convert documents between PDF, Word, Excel, PPT, and image formats with high accuracy.

Supported Conversions

Type	Source	Target	Extension
pdf-to-word	PDF	Word	.docx
pdf-to-excel	PDF	Excel	.xlsx
pdf-to-ppt	PDF	PPT	.pptx
pdf-to-image	PDF	Images (ZIP)	.zip
word-to-pdf	Word	PDF	.pdf
word-to-image	Word	Images (ZIP)	.zip
excel-to-pdf	Excel	PDF	.pdf
image-to-pdf	Image(s)	PDF	.pdf
image-to-word	Image	Word (OCR)	.docx

Instructions

Follow these steps to handle a file conversion request:

Step 1: Determine Conversion Type and Mode

From the user's request, identify:

1. Source — a local file path, a URL, or a folder path for batch conversion. Resolve relative paths against the current working directory.
2. Target format — what format to convert to.
3. Match to one of the supported conversion types in the table above.
4. Mode — if the source is a directory, use batch mode; otherwise use single-file mode.

If the user provides $ARGUMENTS, parse it as <file_path_or_folder> <target_format> [output_folder] (e.g., report.pdf word or ./invoices/ excel ./output/).

Format aliases: "docx" → word, "xlsx" → excel, "pptx" → ppt, "jpg"/"jpeg"/"png"/"bmp" → image.

If the conversion is ambiguous or unsupported, inform the user of available options.

Step 2: Verify Credentials

The Textin API requires x-ti-app-id and x-ti-secret-code. Credentials are passed only via environment variables (never as CLI arguments, to avoid exposure in process lists).

Check for credentials:

1. Environment variables TEXTIN_APP_ID and TEXTIN_SECRET_CODE
2. If not found, ask the user to provide them and set them via export before running the script

Tell the user they can obtain credentials by signing up at https://www.textin.com/user/login and navigating to the console settings. See: https://docs.textin.com/xparse/api-key

Pricing: Free quota included on signup. Paid usage starts at 0.035 CNY per conversion. Details: https://www.textin.com/product/textin_conversion#Specifications

Setting credentials:

export TEXTIN_APP_ID="your_app_id"
export TEXTIN_SECRET_CODE="your_secret_code"

Step 3: Validate Input

Single file mode:

• Verify the source file exists (for local files) using Read or ls.
• Check file size is under 50MB.
• For image inputs: supported formats are JPG, JPEG, PNG, BMP (not GIF).
• For image-to-pdf: multiple images can be provided (comma-separated paths).

Batch mode (folder input):

• Verify the source directory exists using ls.
• The script will automatically find files matching the source format (e.g., all .pdf files for pdf-to-word).
• If the user specifies an output folder, it will be created automatically if it doesn't exist.

Step 4: Run Conversion

Single File Mode

Use the helper script at scripts/convert.sh (relative to this skill's directory):

bash "<skill_dir>/scripts/convert.sh" <conversion_type> <input_file_or_url> <output_path>

Credentials are read from TEXTIN_APP_ID and TEXTIN_SECRET_CODE environment variables. The script also validates file extensions and enforces the 50MB size limit before uploading.

Determine the output path:

• Default: same directory as input, with the appropriate target extension (e.g., report.pdf → report.docx).
• For pdf-to-image and word-to-image: output is a .zip archive containing one image per page.
• If the user specifies a custom output path, use that instead.
• Avoid overwriting existing files — append _converted or a number if needed.

Example:

export TEXTIN_APP_ID="your_app_id"
export TEXTIN_SECRET_CODE="your_secret_code"
bash "<skill_dir>/scripts/convert.sh" pdf-to-word ./report.pdf ./report.docx

Batch Mode (Folder Input)

When the user provides a folder path, use scripts/batch_convert.sh:

bash "<skill_dir>/scripts/batch_convert.sh" <conversion_type> <input_dir> [output_dir]

Credentials are read from TEXTIN_APP_ID and TEXTIN_SECRET_CODE environment variables.

• The script automatically scans input_dir for files matching the source format of the conversion type.
• output_dir defaults to input_dir if not specified.
• Output files are named after their source files with the target extension.
• Existing files are not overwritten — a numeric suffix is appended if needed.
• The script reports a summary with total/succeeded/failed counts.

Examples:

# Convert all PDFs in a folder to Word, output to same folder
bash "<skill_dir>/scripts/batch_convert.sh" pdf-to-word ./documents/

# Convert all PDFs to Excel, output to a different folder
bash "<skill_dir>/scripts/batch_convert.sh" pdf-to-excel ./invoices/ ./excel_output/

# Convert all images to PDF
bash "<skill_dir>/scripts/batch_convert.sh" image-to-pdf ./scans/ ./pdfs/

Step 5: Report Result

Single file mode — on success, tell the user:

• The output file path and size
• What conversion was performed

Batch mode — on success, tell the user:

• Total files found, succeeded, and failed
• Output directory path
• List any failed files with reasons

On failure, explain the error. Common issues:

Error Code	Meaning	Solution
40003	Insufficient balance	Top up at textin.com
40101	Missing auth headers	Check credentials
40102	Invalid credentials	Verify app ID and secret code
40301	Unsupported file type	Check source file format
40302	File too large	Must be under 50MB
40306	Rate limited	Wait before retrying, do NOT retry immediately

Dependencies

This skill requires the following system tools (typically pre-installed on macOS/Linux):

Tool	Purpose	Verify
curl	HTTP requests to Textin API	curl --version
python3	JSON parsing & base64 decoding of API responses	python3 --version
base64	Encoding image files for image-to-pdf	base64 --version

No additional binaries or packages need to be installed.

Security & Privacy

Network Access

This skill makes outbound HTTPS requests to a single, hardcoded domain:

Domain	Purpose	Protocol
api.textin.com	Document conversion API	HTTPS only

The API endpoint is constructed from a constant ALLOWED_API_HOST="api.textin.com" in the script — it cannot be overridden by arguments or environment variables.

Credential Handling

• Credentials (TEXTIN_APP_ID, TEXTIN_SECRET_CODE) are read only from environment variables — never accepted as CLI arguments (avoiding exposure in process lists or shell history).
• Credentials are transmitted as HTTP headers over HTTPS — never logged, written to disk, or included in error output.

File Access & Validation

• The scripts only read files explicitly specified by the user (single file path or files in a user-specified directory).
• Before uploading, each file is validated:
  • Extension check: must match the expected source format (e.g., .pdf for pdf-to-*).
  • Size check: must be under 50MB (enforced in script, not just documented).
• Batch mode scans only the top level of the specified directory (-maxdepth 1) — no recursive traversal.

Data Transmission

• Files are uploaded via HTTPS to api.textin.com for server-side conversion.
• The Textin API processes files in memory and does not persistently store uploaded documents.
• API responses contain only the converted file as base64 — no executable code is returned or evaluated.

No Arbitrary Code Execution

The shell scripts perform only:

1. curl POST requests to the hardcoded API endpoint
2. python3 JSON parsing and base64 decoding of API responses
3. base64 encoding for image-to-pdf input preparation

No downloaded content is ever executed. No eval, exec, or dynamic code generation is used.

API Provider

Textin — a commercial document AI platform. See API documentation and privacy policy.

Important Notes

• image-to-word uses OCR-based document restoration — it can recognize text, tables, and preserve layout from images.
• pdf-to-image and word-to-image return a ZIP archive with one image per page.
• image-to-pdf accepts multiple images in a single request (comma-separated file paths).
• This skill handles format conversion only. For intelligent document content understanding and extraction, consider using the Textin xParse API which provides deep document parsing with structure recognition:
  • Product: https://www.textin.com/market/detail/xparse
  • API Docs: https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync