PDF格式转换高级版 API 简介

说明

Hi，您好，欢迎使用有道智云PDF格式转换高级版 API接口服务。

本文档主要针对需要集成HTTP API的技术开发工程师，详细描述PDF格式转换能力相关的技术内容。

如果您有与我们商务合作的需求，可以通过以下方式联系我们：

商务邮箱： AIcloud_Business@corp.youdao.com

如果您对文档内容有任何疑问，可以通过以下几种方式联系我们：

客服QQ：1906538062

智云翻译技术交流QQ 1群: 652880659

智云翻译技术交流QQ 2群: 669384425

智云翻译技术交流QQ 3群: 807539209

智云翻译技术交流QQ 4群: 936752411

联系邮箱： zhiyun@corp.youdao.com

温馨提示：

• 本文档主要针对开发人员，接入测试前需要获取应用ID和应用密钥；如果您还没有，请按照 新手指南 获取。
• 平台向每个账户赠送50元的体验金，供用户集成前测试所用，具体资费 0.15 元/页。

注：

1. 基础版和高级版接口完全独立，因此高级版上传的文件，转换进度只能通过高级版 API 查询（基础版同理）。
2. 基础版和高级版 转换任务及结果均仅保留7天，转换成功后请及时获取并保存结果。

接口说明

PDF 格式转换接口提供有道的 PDF 转换服务。您只需要通过调用 PDF 转换 API，传入文档的 Base64 编码，就可以将 PDF 文档格式进行转换。

请求流程：upload->query

BASEURL

https://openapi.youdao.com/file_convert/v2

协议须知

公共响应参数

所有接口都遵循统一的响应格式：

文件上传接口

• 接口地址

POST /upload

• 请求参数 (multipart/form-data)

签名生成方法如下：

sign = sha256(应用ID + input + salt + curtime + 应用密钥)

其中，input的计算方式为：

input = q 字符串（当q 长度小于等于20） 或 input = q 前10个字符前10个字符 + q 长度 + q 后十个字符（当q 长度大于20）

• 响应参数 (data字段结构)

• 响应示例

{
    "code": "0",
    "message": "success",
    "data": {
        "flownumber": "BAE670950ACE4C9E941A81B2959CXXXX"
    },
    "requestId": "1580715c-cf43-44d3-bb80-5dd28d1cXXXX",
    "successful": true
}

查询任务状态接口

• 接口地址

POST /query

• 请求参数 (multipart/form-data)

签名生成方法如下：

sign = sha256(应用ID + input + salt + curtime + 应用密钥)

其中，input的计算方式为：

input = flownumber字符串（当flownumber长度小于等于20）。 或 input = flownumber前10个字符前10个字符 + flownumber长度 + flownumber后十个字符（当flownumber长度大于20）

• 响应参数 (data字段结构)

• 状态码说明

• 响应示例

{
    "code": "0",
    "message": "success",
    "data": {
        "status": 4,
        "statusString": "已完成",
        "resultUrl": "https://xxx.nos-jd.163yun.com/xxx"
    },
    "requestId": "d99436d1-7445-44d3-a8e5-e711774aXXXX",
    "successful": true
}

服务配置

错误代码列表

常用语言 Demo

Python 示例

python = 3.11

import base64
import hashlib
import time
import uuid
import requests
import os

# === 请填写你自己的本地文件地址 ===
LOCAL_FILE_PATH = '请填写你自己的本地文件地址'

# === 请填写你自己的应用ID和密钥 ===
APP_KEY = "你的应用ID"
APP_SECRET = "你的应用密钥"

# === 高级版 API 基础URL ===
BASE_URL = "https://openapi.youdao.com/file_convert/v2"
UPLOAD_URL = f"{BASE_URL}/upload"
QUERY_URL = f"{BASE_URL}/query"

def truncate(q: str) -> str:
    """根据文档规则生成 input 字符串"""
    if len(q) <= 20:
        return q
    return q[:10] + str(len(q)) + q[-10:]


def sha256_digest(s: str) -> str:
    """生成 SHA256 签名"""
    return hashlib.sha256(s.encode("utf-8")).hexdigest()


def gen_sign(q_or_flownumber: str) -> tuple:
    """生成签名所需参数：salt, curtime, sign"""
    salt = str(uuid.uuid4())
    curtime = str(int(time.time()))
    input_str = truncate(q_or_flownumber)
    sign_str = APP_KEY + input_str + salt + curtime + APP_SECRET
    sign = sha256_digest(sign_str)
    return salt, curtime, sign


def upload_pdf(file_path: str, target_type="docx"):
    if not os.path.exists(file_path):
        raise FileNotFoundError(file_path)

    with open(file_path, "rb") as f:
        file_base64 = base64.b64encode(f.read()).decode("utf-8")

    salt, curtime, sign = gen_sign(file_base64)

    # 注意 multipart/form-data 传参方式
    form_data = {
        "appKey": (None, APP_KEY),
        "salt": (None, salt),
        "curtime": (None, curtime),
        "sign": (None, sign),
        "signType": (None, "v3"),
        "q": (None, file_base64),
        "fileName": (None, os.path.basename(file_path)),
        "fileType": (None, "pdf"),
        "targetFileType": (None, target_type),
    }

    print("正在以 multipart/form-data 上传文件...")
    resp = requests.post(UPLOAD_URL, files=form_data, timeout=120)
    print(f"HTTP状态: {resp.status_code}")
    print(resp.text)

    result = resp.json()
    if result.get("code") == "0" and result.get("data"):
        flownumber = result["data"]["flownumber"]
        print(f"上传成功，任务流水号: {flownumber}")
        return flownumber
    else:
        raise Exception(f"上传失败: {result}")


def query_task(flownumber: str):
    """查询任务状态（multipart/form-data 方式）"""
    salt, curtime, sign = gen_sign(flownumber)

    form_data = {
        "appKey": (None, APP_KEY),
        "salt": (None, salt),
        "curtime": (None, curtime),
        "sign": (None, sign),
        "signType": (None, "v3"),
        "flownumber": (None, flownumber),
    }

    print(f"查询任务状态: {flownumber}")
    resp = requests.post(QUERY_URL, files=form_data, timeout=30)
    print(f"HTTP状态: {resp.status_code}")
    print(resp.text)

    try:
        result = resp.json()
    except Exception:
        raise Exception(f"返回结果无法解析为JSON: {resp.text}")

    if result.get("code") != "0":
        raise Exception(f"查询失败: {result}")
    return result


def wait_for_result(flownumber: str, interval=5, timeout=300):
    """轮询任务状态直到完成或失败"""
    print("查询任务进度中...")
    start_time = time.time()
    while time.time() - start_time < timeout:
        result = query_task(flownumber)
        data = result.get("data", {})
        status = data.get("status")
        status_str = data.get("statusString", "")
        print(f"任务状态: {status} ({status_str})")

        if status == 4:
            url = data.get("resultUrl")
            print(f"转换完成，下载地址: {url}")
            return url
        elif status == -2:
            raise Exception("转换失败")
        time.sleep(interval)
    raise TimeoutError("任务超时未完成")


def download_result(result_url: str, save_path: str):
    """下载转换后的结果文件"""
    print("正在下载结果...")
    resp = requests.get(result_url)
    with open(save_path, "wb") as f:
        f.write(resp.content)
    print(f"文件已保存到: {save_path}")


if __name__ == "__main__":
    # === 示例使用 ===
    # 输出的Word文件名
    output_file = "result.docx"

    flownumber = upload_pdf(LOCAL_FILE_PATH, target_type="docx")
    result_url = wait_for_result(flownumber)
    # 保存文件到本地
    download_result(result_url, output_file)