bl parsex submits document or media parsing tasks, extracts fields from a document or an existing parse result with a JSON Schema, and queries parse and extraction results.
ParseX uses a workspace-specific API and a standard API Key. Provide the workspace with --workspace-id, BAILIAN_WORKSPACE_ID, or the workspace_id config field. Service availability depends on the workspace and rollout.
Append --help to any command for full parameter details, e.g. bl parsex parse submit --help. Submit commands return data.biz_id immediately without waiting; use the matching result --follow to wait. Command details on this page are verified against bl 2.8.0.
See Use the CLI for feature-page usage.
Quick start
bl parsex parse submit --workspace-id <workspace-id> --file-url "https://example.com/document.pdf" --file-name document.pdf --output-file-format markdown --output json
bl parsex parse result --workspace-id <workspace-id> --biz-id <parse-biz-id> --follow --output json
bl parsex extract submit --workspace-id <workspace-id> --parsed-file-biz-id <parse-biz-id> --schema-file schema.json --output json
bl parsex extract result --workspace-id <workspace-id> --biz-id <extract-biz-id> --follow --output json
Document parsing
bl parsex parse submit
Submit a ParseX document or media parsing task. Requires API Key authentication.
Usage
bl parsex parse submit --file-url <url> [--workspace-id <id>] [flags]
| Parameter | Type | Required | Description |
|---|
--file-url <url> | string | yes | Accessible source file URL |
--file-name <name> | string | no | File name (alternative to --file-name-extension) |
--file-name-extension <extension> | string | no | File extension, e.g. pdf |
--config-id <id> | string | no | Saved ParseX configuration ID |
--processing-file <path> | string | no | JSON object file for the API processing field |
--oss-config-file <path> | string | no | JSON file with OSS credentials; the file must also include bucket and endpoint |
--output-file-format <markdown> | array | no | Result file format (markdown) |
--layout-table-format <markdown|html> | string | no | Table format inside Markdown results |
--workspace-id <id> | string | no | Workspace ID for the API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
--api-key <key> | string | no | API key |
--base-url <url> | string | no | API base URL |
Example: Submit a document parsing task
bl parsex parse submit --file-url "https://example.com/document.pdf" --file-name document.pdf --workspace-id ws-example
Example: Use a processing configuration and request Markdown output
bl parsex parse submit --file-url "https://example.com/document.pdf" --processing-file processing.json --output-file-format markdown --output json
Example: Preview submission parameters
bl parsex parse submit --file-url "https://example.com/video.mp4" --config-id config-example --dry-run
- Input must be an accessible HTTP(S) URL, including a signed OSS URL. This API does not support uploading local files.
- Inline processing configuration takes precedence over
--config-id.
- Processing configuration example:
{"doc_processing_config":{"page_index":"1-10","layout_position":true}}. For media, use media_processing_config with diarization, synopsis, and frame extraction.
- Dry-run makes no business requests and redacts OSS credentials and URL query strings.
bl parsex parse result
Query ParseX parsing status, results, or a result slice. Requires API Key authentication.
Usage
bl parsex parse result --biz-id <id> [--follow] [flags]
| Parameter | Type | Required | Description |
|---|
--biz-id <id> | string | yes | biz_id returned by the matching submit command |
--follow | switch | no | Poll until success or failure (Ctrl-C stops only local polling) |
--interval <seconds> | number | no | Polling interval, 1–3600 seconds (default: 2; --follow only) |
--poll-timeout <seconds> | number | no | Total polling deadline, 1–86400 seconds (default: 600; --follow only) |
--step-start <n> | number | no | Slice offset for layouts or media segments (service default: 0) |
--step-size <n> | number | no | Slice size (service default: 0) |
--oss-config-file <path> | string | no | JSON file with OSS credentials |
--workspace-id <id> | string | no | Workspace ID for the API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
Example: Query parsing results
bl parsex parse result --biz-id biz-example --workspace-id ws-example
Example: Wait for completion and output JSON
bl parsex parse result --biz-id biz-example --follow --poll-timeout 600 --output json
- Single queries preserve the complete API response and exit 0 even for a failed job.
--follow emits one terminal response on stdout and progress on stderr; failure exits 1, deadline 5, Ctrl-C 130.
- Resume with the same
biz_id; stopping locally does not cancel the task.
ResultNotReady is polled again only with --follow.
--timeout controls each HTTP request; --poll-timeout covers the whole polling loop.
--follow waits for task completion for the requested slice; it does not collect all slices. Advance --step-start explicitly to retrieve further layouts or segments.
- Output file URLs may appear only after all results have been retrieved.
Submit ParseX structured field extraction. Requires API Key authentication.
Usage
bl parsex extract submit (--file-url <url> | --parsed-file-biz-id <id>) (--schema-file <path> | --processing-file <path> | --config-id <id>) [flags]
| Parameter | Type | Required | Description |
|---|
--file-url <url> | string | no | Accessible source file URL |
--file-name <name> | string | no | File name (alternative to --file-name-extension) |
--file-name-extension <extension> | string | no | File extension, e.g. pdf |
--config-id <id> | string | no | Saved ParseX configuration ID |
--processing-file <path> | string | no | JSON object file for the API processing field |
--parsed-file-biz-id <id> | string | no | Completed parsing task to reuse (alternative to --file-url) |
--schema-file <path> | string | no | JSON Schema object file (alternative to --processing-file) |
--user-prompt <text> | string | no | Extraction instruction (with --schema-file) |
--citation-required <boolean> | boolean | no | Include citations (with --schema-file; service default: true) |
--allow-inference <boolean> | boolean | no | Allow inference (with --schema-file; service default: false) |
--oss-config-file <path> | string | no | JSON file with OSS credentials; the file must also include bucket and endpoint |
--workspace-id <id> | string | no | Workspace ID for the API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
Example: Extract fields from a document
bl parsex extract submit --file-url "https://example.com/contract.pdf" --schema-file schema.json --workspace-id ws-example
Example: Reuse a parse result and include citations
bl parsex extract submit --parsed-file-biz-id parse-example --schema-file schema.json --citation-required true --allow-inference false
Example: Use a saved configuration
bl parsex extract submit --file-url "https://example.com/contract.pdf" --config-id config-example --output json
- Returns
data.biz_id without waiting. Query with extract result --follow.
- The schema is sent as an object, not a JSON string. Example:
{"type":"object","properties":{"title":{"type":"string"}}}.
- Extraction does not support audio or video. Reused parse results must still be retained by the service.
- As with parsing, input must be an accessible HTTP(S) URL, and dry-run makes no business requests.
Query ParseX extraction status, fields, and citations. Requires API Key authentication.
Usage
bl parsex extract result --biz-id <id> [--follow] [flags]
Parameters, polling behavior, and exit codes match bl parsex parse result, except for --step-start and --step-size.
Example: Query extraction results
bl parsex extract result --biz-id biz-example --workspace-id ws-example
Example: Wait for extraction and output JSON
bl parsex extract result --biz-id biz-example --follow --poll-timeout 600 --output json
- Single queries preserve the complete API response and exit 0 even for a failed job.
--follow waits for a terminal state; failure exits 1, deadline 5, Ctrl-C 130.
Notes
- When
--base-url overrides the endpoint origin, the CLI discards its path. cn-beijing.pre-maas.aliyuncs.com workspace hosts use pre-parse-x.
- The service retains parse results for a limited time. Extract from them promptly when reuse is needed.