数据传输AI服务DTS-AI通过API解析PDF Word PPT文档-数据传输服务(DTS)-阿里云帮助中心

本文介绍如何通过DTS-AI服务的API将PDF、Word等格式的文档解析为Markdown格式，并提供curl、SDK、阿里云CLI和DTS Skill四种调用方式的完整示例。

方案概览

DTS-AI 服务提供文档解析能力，支持将 PDF、Word、PPT、纯文本、Markdown 及图片等多种格式的文档解析为 Markdown 格式的结构化内容。

文档解析支持同步和异步两种调用方式。同步方式较为简单，只需将核心参数 ResponseMode 设置为 sync 即可。

本文档以异步方式为主线进行讲解，同步方式将在方式三：使用SDK同步调用（AccessKey认证）中具体说明。异步调用的整体流程如下：

创建解析任务：调用CreateDocParserJob接口提交文档解析任务，获取任务ID（JobId）。
查询任务状态：调用DescribeDocParserJobStatus接口轮询任务状态，直到状态变为success。
获取解析结果：调用DescribeDocParserJobResult接口获取解析后的Markdown内容。

快速体验

如果您希望在集成SDK或CLI之前先快速验证文档解析能力，可以通过阿里云OpenAPI开发者门户在线调试DTS-AI服务的API：

创建文档解析任务：CreateDocParserJob在线调试。
查询任务状态：DescribeDocParserJobStatus在线调试。
获取解析结果：DescribeDocParserJobResult在线调试。

登录并授权后，在页面左侧填写请求参数，单击发起调用即可查看返回结果。调试通过后，再参考下方SDK或CLI示例集成到您的应用中。

适用范围

在调用DTS-AI服务的API之前，请完成以下准备工作。

准备认证凭证

DTS-AI服务支持以下两种认证凭证，任选其一。推荐使用API Key，凭证权限仅限定在DTS服务范围内，安全风险更可控。

API Key（推荐）：API Key是RAM为单个云服务签发的服务凭证，只能调用绑定云服务的OpenAPI，权限范围更小。您可在RAM控制台在指定用户的凭证管理区域内，单击创建 API Key，云服务选择数据传输服务 / DTS，创建后立即复制凭证明文并妥善保存（关闭弹窗后无法再次获取）。具体操作，请参见创建 API Key。
重要
- 阿里云账号（主账号）不支持创建API Key，只能通过RAM用户创建。每个RAM用户在每个云服务下最多创建2个API Key。
- API Key是访问云服务的凭证，泄漏后任何人都可以调用您的服务与API，产生不可预估的费用和安全风险。请务必妥善保管，不要将API Key明文写入代码、提交到代码仓库或发布到公共平台。推荐使用环境变量存储，详见下方“配置API Key环境变量”章节。
AccessKey ID和AccessKey Secret：适用于需要复用现有阿里云AccessKey凭证的场景。为保证安全，建议使用RAM用户的AccessKey，并遵循最小权限原则配置权限策略。具体操作，请参见通过系统策略授权子账号管理DTS。

说明

下方示例通过环境变量读取凭证：

API Key读取DTS_AI_API_KEY。
AccessKey读取ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。

运行示例前，请先在操作系统中配置对应的环境变量，避免将凭证硬编码到代码中。凭证的安全使用方法，请参见管理访问凭据。

准备调用工具（按需选择）

使用curl方式：无需额外安装，仅需API Key即可发起调用。适合快速验证API或简单集成场景。
使用SDK方式：已安装DtsAI SDK。您可以通过SDK下载页面获取各语言的SDK。
使用阿里云CLI方式：已安装并配置阿里云CLI。具体操作，请参见安装/更新 CLI和配置与管理身份凭证。

注意事项

文档解析API目前仅支持华北2（北京）地域，RegionId请填写cn-beijing。
FileUrl参数必须为有效的OSS URL地址。如果文件不在OSS上，建议使用SDK的CreateDocParserJobAdvance方法直接传入本地文件流。
输出格式（OutputFormat）当前仅支持markdown。
解析结果保留72小时，过期后将无法获取，请及时下载保存。
支持解析的文件格式包括：PDF、DOCX、DOC、PPTX、PPT、TXT、Markdown、PNG、JPG、JPEG。
各语言SDK提供CreateDocParserJobAdvance方法，支持直接传入本地文件流，无需将文件上传至OSS后再传入URL。

方式一：使用curl直接调用（推荐，API Key认证）

通过X-Acs-ApiKey请求头传入API Key，即可直接调用DTS-AI服务的API。无需签名计算，适合快速验证或轻量级集成场景。

步骤一：配置API Key环境变量

将创建好的API Key配置为环境变量，避免明文出现在命令中。

export DTS_AI_API_KEY='<您的API Key>'

步骤二：创建文档解析任务

调用CreateDocParserJob接口创建文档解析任务。

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"
  }'

返回结果示例：

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

记录返回结果中的JobId，后续步骤中使用该ID查询任务状态和获取结果。

步骤三：查询任务状态

调用DescribeDocParserJobStatus接口轮询任务状态，直到返回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"
  }'

步骤四：获取解析结果

任务状态为success后，调用DescribeDocParserJobResult接口获取解析结果。

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"
  }'

返回结果中的Result字段即为解析后的Markdown格式内容。

方式二：使用SDK异步调用（AccessKey认证）

以下以Java SDK为例，演示文档解析的完整流程。其他语言的SDK用法类似，请参见SDK下载页面。

步骤一：安装SDK

在Maven项目的pom.xml文件中添加以下依赖：

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

步骤二：创建异步文档解析任务

调用CreateDocParserJob接口创建文档解析任务。如果文件在本地，可以使用CreateDocParserJobAdvance方法直接传入文件流。

通过文件URL创建解析任务

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 {
        // 初始化客户端
        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);

        // 创建解析任务
        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("任务创建成功，JobId: " + jobId);
    }
}

通过本地文件流创建解析任务（Advance方法）

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);

        // 使用Advance方法直接传入本地文件流
        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("任务创建成功，JobId: " + jobId);
    }
}

步骤三：查询任务状态

调用DescribeDocParserJobStatus接口轮询任务状态，直到返回success。

// 轮询任务状态
DescribeDocParserJobStatusRequest statusRequest = new DescribeDocParserJobStatusRequest()
    .setRegionId("cn-beijing")
    .setJobId(jobId);

String status = "";
while (!"success".equals(status) && !"failed".equals(status)) {
    Thread.sleep(5000); // 每5秒查询一次
    DescribeDocParserJobStatusResponse statusResponse =
        client.describeDocParserJobStatus(statusRequest);
    status = statusResponse.getBody().getStatus();
    System.out.println("当前状态: " + status);

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

任务状态（Status）的取值说明如下：

状态值	说明
`init`	已创建，准备中。
`pending`	排队中，等待调度执行。
`running`	处理中，正在解析文档。
`success`	解析完成，可调用DescribeDocParserJobResult获取结果。
`failed`	解析失败，可通过FailureMessage获取失败原因。
`cancelled`	任务已取消。

步骤四：获取解析结果

任务状态为success后，调用DescribeDocParserJobResult接口获取解析结果。

// 获取解析结果
DescribeDocParserJobResultRequest resultRequest = new DescribeDocParserJobResultRequest()
    .setRegionId("cn-beijing")
    .setJobId(jobId);

DescribeDocParserJobResultResponse resultResponse =
    client.describeDocParserJobResult(resultRequest);
String markdownContent = resultResponse.getBody().getResult();
System.out.println("解析结果:\n" + markdownContent);

重要

解析结果仅保留72小时，请在任务完成后及时获取并保存结果。

方式三：使用SDK同步调用（AccessKey认证）

以下以Java SDK为例，演示文档解析的完整流程。其他语言的SDK用法类似，请参见SDK下载页面。

步骤一：安装SDK

在Maven项目的pom.xml文件中添加以下依赖：

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

步骤二：创建同步文档解析任务

调用CreateDocParserJob接口创建文档解析任务。如果文件在本地，可以使用CreateDocParserJobAdvance方法直接传入文件流。

通过文件URL创建解析任务

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 {
        // 初始化客户端
        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);

        // 创建解析任务
        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("任务创建成功，JobId: " + jobId);
    }
}

通过本地文件流创建解析任务（Advance方法）

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);

        // 使用Advance方法直接传入本地文件流
        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("任务创建成功，JobId: " + jobId);
    }
}

返回结果如下：

{
  "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$$"
}

方式四：使用阿里云CLI调用

以下示例演示如何通过阿里云CLI完成文档解析的完整流程。使用前请确认：

已升级阿里云CLI至最新版，并安装aliyun-cli-dtsai插件，具体命令如下：
```
aliyun plugin install --names aliyun-cli-dtsai
```
已完成阿里云CLI的身份认证配置。推荐使用OAuth模式（免维护AccessKey），执行aliyun configure --mode OAuth按提示登录即可；您也可以选择AccessKey或STS Token等其他认证方式，具体操作，请参见配置与管理身份凭证。

说明

DTS-AI服务的CLI命令通过aliyun-cli-dtsai插件提供，命令与参数均采用短横线命名（kebab-case），例如aliyun dtsai web-search --biz-region-id cn-beijing --query "..."。

步骤一：创建文档解析任务

执行以下命令，调用create-doc-parser-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

返回结果示例：

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

记录返回结果中的JobId，后续步骤中使用该ID查询任务状态和获取结果。

步骤二：查询任务状态

执行以下命令，调用describe-doc-parser-job-status命令查询解析任务的状态。

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

返回结果示例：

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

重复执行该命令，直到Status变为success。如果返回failed，请查看FailureMessage字段获取失败原因。

步骤三：获取解析结果

任务状态为success后，执行以下命令获取解析结果。

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

返回结果示例：

{
  "HttpStatusCode": 200,
  "RequestId": "019F64F3-75D0-583C-B54D-7E0522689216",
  "Result": "# 什么是数据传输服务DTS\n\n数据传输服务DTS（Data Transmission Service）是阿里云提供的一站式数据传输与处理平台...",
  "Success": true
}

返回结果中的Result字段即为解析后的Markdown格式内容。

方式五：在编程Agent中通过DTS Skill调用

DTS提供官方Skill，支持在Qoder、Claude Code、Cursor、Codex等编程Agent中以自然语言调用DTS-AI服务的文档解析能力，无需手动编写API调用代码。Skill底层复用本文介绍的API，适用于本地文档批量解析、交互式数据处理等场景。

步骤一：安装Skill

执行以下命令，一键安装DTS全部Skill（包含文档解析、网页搜索、DTS任务管理3个Skill）。

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

如果只需要文档解析能力，可以通过--skill参数单独安装对应Skill。

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

--agent参数支持的编程Agent及默认安装目录如下。

参数值	编程Agent	默认安装目录
`codex`	Codex	`~/.codex/skills`
`claude`	Claude Code	`~/.claude/skills`
`cursor`	Cursor	`~/.cursor/skills`
`zcode`	ZCode	`~/.zcode/skills`
`qoder`	Qoder	`~/.qoder/skills`
`qoderwork`	QoderWork	`~/.qoderwork/skills`
`qwenworkcn`	千问办公	`~/.qwenworkcn/skills`
`opencode`	OpenCode	`~/.config/opencode/skills`
`kimi`	Kimi Code	`~/.kimi/skills`

说明

Skill依赖Python 3运行，安装前请确认系统已安装Python 3。
如需升级Skill至最新版本，重新执行上述安装命令即可，安装程序会自动备份已有Skill并完成升级。

步骤二：配置API Key

文档解析Skill使用API Key认证，API Key的创建方法请参见准备认证凭证。首次使用Skill时，Skill会自动引导您完成API Key配置，配置成功后凭证保存在~/.aliyun-dts/dts-ai/credentials.json文件中，后续会话无需重复配置。您也可以通过DTS_AI_API_KEY环境变量传入API Key。

步骤三：在编程Agent中使用

安装并配置完成后，在编程Agent中通过自然语言描述需求即可调用Skill完成文档解析。示例如下：

使用dts skill，将/path/to/document.pdf解析为Markdown

编程Agent将自动调用文档解析API完成任务，并返回解析后的Markdown内容。

API	说明
CreateDocParserJob	创建文档解析任务。
DescribeDocParserJobStatus	查询文档解析任务的状态。
DescribeDocParserJobResult	获取文档解析任务的结果。需在任务状态为success后调用，结果保留72小时。

方案概览

快速体验

适用范围

准备认证凭证

准备调用工具（按需选择）

注意事项

方式一：使用curl直接调用（推荐，API Key认证）

步骤一：配置API Key环境变量

步骤二：创建文档解析任务

步骤三：查询任务状态

步骤四：获取解析结果

方式二：使用SDK异步调用（AccessKey认证）

步骤一：安装SDK

步骤二：创建异步文档解析任务

通过文件URL创建解析任务

通过本地文件流创建解析任务（Advance方法）

步骤三：查询任务状态

步骤四：获取解析结果

方式三：使用SDK同步调用（AccessKey认证）

步骤一：安装SDK

步骤二：创建同步文档解析任务

通过文件URL创建解析任务

通过本地文件流创建解析任务（Advance方法）

方式四：使用阿里云CLI调用

步骤一：创建文档解析任务

步骤二：查询任务状态

步骤三：获取解析结果

方式五：在编程Agent中通过DTS Skill调用

步骤一：安装Skill

步骤二：配置API Key

步骤三：在编程Agent中使用

相关API