Textin File Converter Pro#

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

Supported Conversions#

TypeSourceTargetExtensionpdf-to-wordPDFWord.docxpdf-to-excelPDFExcel.xlsxpdf-to-pptPDFPPT.pptxpdf-to-imagePDFImages (ZIP).zipword-to-pdfWordPDF.pdfword-to-imageWordImages (ZIP).zipexcel-to-pdfExcelPDF.pdfimage-to-pdfImage(s)PDF.pdfimage-to-wordImageWord (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:

bash

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

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:

bash

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

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:

bash

# 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 CodeMeaningSolution40003Insufficient balanceTop up at textin.com40101Missing auth headersCheck credentials40102Invalid credentialsVerify app ID and secret code40301Unsupported file typeCheck source file format40302File too largeMust be under 50MB40306Rate limitedWait before retrying, do NOT retry immediately

Dependencies#

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

ToolPurposeVerifycurlHTTP requests to Textin APIcurl --version``python3JSON parsing & base64 decoding of API responsespython3 --version``base64Encoding 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:

DomainPurposeProtocolapi.textin.comDocument conversion APIHTTPS 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