Parse documents with DTS-AI

Prepare authentication credentials

The DTS-AI service supports two types of authentication credentials. Choose either one. API Key is recommended because its permissions are restricted to the DTS service scope, resulting in more controllable security risks.

• API Key (recommended): An API Key is a service credential issued by RAM for a single cloud service. It can only call the OpenAPIs of the bound cloud service, resulting in a smaller permission scope. In the RAM console, locate the target user, go to the Credential Management section, click Create API Key, and set Cloud Service to Data Transmission Service / DTS. After the API Key is created, copy the plaintext credential immediately and store it securely (the plaintext is unavailable after the dialog is closed). For more information, see Create an API key.

  Important

  • Alibaba Cloud accounts (root accounts) cannot create API Keys. Only RAM users can create them. Each RAM user can create up to 2 API Keys per cloud service.

  • An API Key is a credential used to access cloud services. If it is leaked, anyone can call your APIs, resulting in unpredictable costs and security risks. Keep your API Key secure and do not write it in plaintext in code, commit it to code repositories, or publish it to public platforms. We recommend that you store it in environment variables. For more information, see the "" section below.

• AccessKey ID and AccessKey Secret: Suitable for scenarios where you want to reuse existing Alibaba Cloud AccessKey credentials. For security, we recommend using the AccessKey of a RAM user and configuring a permission policy based on the principle of least privilege. For more information, see Authorize a RAM user to manage DTS.

Prepare a calling tool (choose as needed)

• Use curl: No additional installation is required. You only need an API Key to initiate calls. Suitable for quick API verification or lightweight integration scenarios.

• Use the SDK: You have installed the DtsAI SDK. You can obtain SDKs for various languages from the SDK download page.

• Use the Alibaba Cloud CLI: You have installed and configured the Alibaba Cloud CLI. For more information, see Install, update, and uninstall Alibaba Cloud CLI and Configure and manage credentials.

Step 1: Configure the API Key environment variable

Configure the API Key as an environment variable to avoid exposing the plaintext in commands.

export DTS_AI_API_KEY='<your API Key>'

Step 2: Create a document parsing job

Call the CreateDocParserJob operation to create a document parsing job.

curl -X POST \
  "https://dtsai.cn-beijing.aliyuncs.com?Action=CreateDocParserJob&Version=2026-04-01&SignatureNonce=$(uuidgen)" \
  --header "X-Acs-ApiKey: ${DTS_AI_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-raw '{
    "RegionId": "cn-beijing",
    "FileUrl": "https://<BucketName>.oss-cn-beijing.aliyuncs.com/document.pdf",
    "FileName": "document.pdf",
    "FileFormat": "pdf",
    "OutputFormat": "markdown"
  }'

Sample response:

{
  "RequestId": "019F6482-DD04-510E-A212-A21B3C59CB8C",
  "Success": true,
  "HttpStatusCode": 200,
  "JobId": "job_abc123"
}

Note the JobId from the response. Use this ID in the following steps to query the job status and get the parsing result.

Step 3: Query the job status

Call the DescribeDocParserJobStatus operation to poll the job status until it returns success.

curl -X POST \
  "https://dtsai.cn-beijing.aliyuncs.com?Action=DescribeDocParserJobStatus&Version=2026-04-01&SignatureNonce=$(uuidgen)" \
  --header "X-Acs-ApiKey: ${DTS_AI_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "RegionId": "cn-beijing",
    "JobId": "job_abc123"
  }'

Step 4: Get the parsing result

After the job status is success, call the DescribeDocParserJobResult operation to get the parsing result.

curl -X POST \
  "https://dtsai.cn-beijing.aliyuncs.com?Action=DescribeDocParserJobResult&Version=2026-04-01&SignatureNonce=$(uuidgen)" \
  --header "X-Acs-ApiKey: ${DTS_AI_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "RegionId": "cn-beijing",
    "JobId": "job_abc123"
  }'

The Result field in the response contains the parsed content in Markdown format.

Step 1: Install the SDK

Add the following dependency to the pom.xml file of your Maven project:

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>dtsai20260401</artifactId>
  <version>1.0.0</version>
</dependency>

Step 2: Create a document parsing job

Call the CreateDocParserJob API to create a document parsing job. If the file is stored locally, you can use the CreateDocParserJobAdvance method to pass the file stream directly.

import com.aliyun.dtsai20260401.Client;
import com.aliyun.dtsai20260401.models.*;
import com.aliyun.teaopenapi.models.Config;

public class DocParserExample {
    public static void main(String[] args) throws Exception {
        // Initialize the client.
        Config config = new Config()
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "dtsai.cn-beijing.aliyuncs.com";
        Client client = new Client(config);

        // Create a parsing job.
        CreateDocParserJobRequest request = new CreateDocParserJobRequest()
            .setRegionId("cn-beijing")
            .setFileUrl("https://example.oss-cn-beijing.aliyuncs.com/document.pdf")
            .setFileName("document.pdf")
            .setFileFormat("pdf")
            .setOutputFormat("markdown");

        CreateDocParserJobResponse response = client.createDocParserJob(request);
        String jobId = response.getBody().getJobId();
        System.out.println("Job created successfully. JobId: " + jobId);
    }
}

import com.aliyun.dtsai20260401.Client;
import com.aliyun.dtsai20260401.models.*;
import com.aliyun.teaopenapi.models.Config;
import java.io.FileInputStream;

public class DocParserAdvanceExample {
    public static void main(String[] args) throws Exception {
        Config config = new Config()
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "dtsai.cn-beijing.aliyuncs.com";
        Client client = new Client(config);

        // Use the Advance method to directly pass a local file stream.
        CreateDocParserJobAdvanceRequest request = new CreateDocParserJobAdvanceRequest()
            .setRegionId("cn-beijing")
            .setFileUrlObject(new FileInputStream("/path/to/document.pdf"))
            .setFileName("document.pdf")
            .setFileFormat("pdf")
            .setOutputFormat("markdown");

        CreateDocParserJobResponse response = client.createDocParserJobAdvance(request,
            new com.aliyun.teautil.models.RuntimeOptions());
        String jobId = response.getBody().getJobId();
        System.out.println("Job created successfully. JobId: " + jobId);
    }
}

Step 3: Query the job status

Call the DescribeDocParserJobStatus operation to poll the job status until it returns success.

// Poll the job status
DescribeDocParserJobStatusRequest statusRequest = new DescribeDocParserJobStatusRequest()
    .setRegionId("cn-beijing")
    .setJobId(jobId);

String status = "";
while (!"success".equals(status) && !"failed".equals(status)) {
    Thread.sleep(5000); // Query every 5 seconds
    DescribeDocParserJobStatusResponse statusResponse =
        client.describeDocParserJobStatus(statusRequest);
    status = statusResponse.getBody().getStatus();
    System.out.println("Current status: " + status);

    if ("failed".equals(status)) {
        System.out.println("Job failed: " + statusResponse.getBody().getFailureMessage());
        return;
    }
}

The following table describes the job status values.

Step 4: Get the parsing result

After the job status changes to success, call the DescribeDocParserJobResult API to get the parsing result.

// Get the parsing result
DescribeDocParserJobResultRequest resultRequest = new DescribeDocParserJobResultRequest()
    .setRegionId("cn-beijing")
    .setJobId(jobId);

DescribeDocParserJobResultResponse resultResponse =
    client.describeDocParserJobResult(resultRequest);
String markdownContent = resultResponse.getBody().getResult();
System.out.println("Parsing result:\n" + markdownContent);

Step 1: Install the SDK

Add the following dependency to the pom.xml file of your Maven project:

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>dtsai20260401</artifactId>
  <version>1.0.0</version>
</dependency>

Step 2: Create a synchronous document parsing job

Call the CreateDocParserJob API to create a document parsing job. To parse a local file, use the CreateDocParserJobAdvance method to pass the file stream directly.

import com.aliyun.dtsai20260401.Client;
import com.aliyun.dtsai20260401.models.*;
import com.aliyun.teaopenapi.models.Config;

public class DocParserExample {
    public static void main(String[] args) throws Exception {
        // Initialize client
        Config config = new Config()
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "dtsai.cn-beijing.aliyuncs.com";
        Client client = new Client(config);

        // Create a parsing job
        CreateDocParserJobRequest request = new CreateDocParserJobRequest()
            .setRegionId("cn-beijing")
            .setFileUrl("https://example.oss-cn-beijing.aliyuncs.com/document.pdf")
            .setFileName("document.pdf")
            .setFileFormat("pdf")
            .setOutputFormat("markdown")
            .setResultType("content")
            .setResponseMode("sync");

        CreateDocParserJobResponse response = client.createDocParserJob(request);
        String jobId = response.getBody().getJobId();
        System.out.println("Job created successfully. JobId: " + jobId);
    }
}

import com.aliyun.dtsai20260401.Client;
import com.aliyun.dtsai20260401.models.*;
import com.aliyun.teaopenapi.models.Config;
import java.io.FileInputStream;

public class DocParserAdvanceExample {
    public static void main(String[] args) throws Exception {
        Config config = new Config()
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "dtsai.cn-beijing.aliyuncs.com";
        Client client = new Client(config);

        // Use the Advance method to pass a local file stream directly
        CreateDocParserJobAdvanceRequest request = new CreateDocParserJobAdvanceRequest()
            .setRegionId("cn-beijing")
            .setFileUrlObject(new FileInputStream("/path/to/document.pdf"))
            .setFileName("document.pdf")
            .setFileFormat("pdf")
            .setOutputFormat("markdown")
            .setResultType("content")
            .setResponseMode("sync");

        CreateDocParserJobResponse response = client.createDocParserJobAdvance(request,
            new com.aliyun.teautil.models.RuntimeOptions());
        String jobId = response.getBody().getJobId();
        System.out.println("Job created successfully. JobId: " + jobId);
    }
}

The returned result is as follows:

{
  "Status": "success",
  "RequestId": "01A055D1-178A-5292-9230-****",
  "HttpStatusCode": 200,
  "ResultType": "content",
  "Success": true,
  "JobId": "01a055d1-17bd-7ed2-ba59-****",
  "Result": "<!-- page 1 -->\n\n# DTS FORMULA MARKDOWN 2026\n\n$$\nx = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}\n$$"
}

Step 1: Create a document parsing job

Run the following command to call the create-doc-parser-job command and create a document parsing job.

aliyun dtsai create-doc-parser-job \
  --endpoint dtsai.cn-beijing.aliyuncs.com \
  --biz-region-id cn-beijing \
  --file-url "https://<BucketName>.oss-cn-beijing.aliyuncs.com/document.pdf" \
  --file-name document.pdf \
  --file-format pdf \
  --output-format markdown

Sample response:

{
  "HttpStatusCode": 200,
  "JobId": "019f64f2-565d-7d70-95d0-3b97d784a113",
  "RequestId": "019F64F2-561D-522C-8F56-71D8D3E8F62A",
  "Success": true
}

Note the JobId from the response. Use this ID in the following steps to query the job status and get the parsing result.

Step 2: Query the job status

Run the following command to call the describe-doc-parser-job-status command and query the status of the parsing job.

aliyun dtsai describe-doc-parser-job-status \
  --endpoint dtsai.cn-beijing.aliyuncs.com \
  --biz-region-id cn-beijing \
  --job-id 019f64f2-565d-7d70-95d0-3b97d784a113

Sample response:

{
  "HttpStatusCode": 200,
  "RequestId": "019F64F2-F9AC-5F55-8EFC-65729321A64C",
  "Status": "success",
  "Success": true
}

Run this command repeatedly until the Status is success. If the status is failed, check the FailureMessage field for the failure message.

Step 3: Get the parsing result

After the job status is success, run the following command to get the parsing result.

aliyun dtsai describe-doc-parser-job-result \
  --endpoint dtsai.cn-beijing.aliyuncs.com \
  --biz-region-id cn-beijing \
  --job-id 019f64f2-565d-7d70-95d0-3b97d784a113

Sample response:

{
  "HttpStatusCode": 200,
  "RequestId": "019F64F3-75D0-583C-B54D-7E0522689216",
  "Result": "# What is Data Transmission Service (DTS)?\n\nData Transmission Service (DTS) is a one-stop data transmission and processing platform provided by Alibaba Cloud...",
  "Success": true
}

The Result field in the response contains the parsed content in Markdown format.

Step 1: Install the Skill

Run the following command to install all DTS Skills (three Skills in total: document parsing, web search, and DTS task management) in one go.

curl -fsSL 'https://aliyun-dts-skills.oss-cn-hangzhou.aliyuncs.com/install.sh' | bash -s -- --agent <Agent Param>

If you only need the document parsing capability, use the --skill parameter to install the corresponding Skill individually.

curl -fsSL 'https://aliyun-dts-skills.oss-cn-hangzhou.aliyuncs.com/install.sh' | bash -s -- --agent <Agent Param> --skill aliyun-dts-doc-parse

The --agent parameter supports the following coding agents. The default installation directory of each agent is also listed.

Step 2: Configure the API Key

The document parsing Skill uses API Key authentication. For how to create an API Key, see prepare authentication credentials. When you use the Skill for the first time, the Skill automatically guides you through the API Key configuration. After the configuration succeeds, the credential is saved in the ~/.aliyun-dts/dts-ai/credentials.json file, and no repeated configuration is needed in subsequent sessions. You can also pass the API Key through the DTS_AI_API_KEY environment variable.

Step 3: Use the Skill in a coding agent

After the installation and configuration are complete, describe your requirement in natural language in the coding agent to invoke the Skill for document parsing. Example:

Use the dts skill to parse /path/to/document.pdf into Markdown

The coding agent automatically calls the document parsing API to complete the task and returns the parsed Markdown content.