All Products
Search
Document Center

Alibaba Cloud Model Studio:PDF understanding

Last Updated:Nov 20, 2026

The PDF understanding feature enables models to parse text and images in PDF documents, and analyze them through Chat Completions, the Responses API, DashScope, or the Anthropic-compatible API.

Supported models

qwen4-max、qwen3.8-max、qwen3.8-max-0902、qwen3.8-flash、qwen3.8-27b

qwen3.8-27b supports PDF understanding only in the Beijing region via Chat Completions or DashScope.

QuickStart

Run the following code to pass a PDF file to the model.

You must have already obtained and configured an API Key and configured the API Key as an environment variable.

OpenAI compatible

Python

Sample Code

from openai import OpenAI
import os

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"(不建议),
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为新加坡地域的URL,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "file",
                    "file": {
                        "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
                    }
                },
                {
                    "type": "text",
                    "text": "总结一下这个PDF文档的内容"
                }
            ]
        }
    ],
    stream=True,
    stream_options={"include_usage": True},
    # 需要开启该参数才会在 usage 中返回 x_tools.pdf_page_parser.count(PDF解析页数)
    extra_body={"include_tool_usage": True}
)

for chunk in completion:
    if not chunk.choices:
        print(f"\nUsage: {chunk.usage}")
        continue
    delta = chunk.choices[0].delta
    if hasattr(delta, "content") and delta.content:
        print(delta.content, end="", flush=True)

Node.js

Sample Code

import OpenAI from "openai";
import process from 'process';

const openai = new OpenAI({
    // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
    apiKey: process.env.DASHSCOPE_API_KEY,
    // 以下为新加坡地域的URL,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的URL不同。
    baseURL: 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1'
});

async function main() {
    const stream = await openai.chat.completions.create({
        model: 'qwen4-max',
        messages: [
            {
                role: 'user',
                content: [
                    {
                        type: 'file',
                        file: {
                            file_url: 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf'
                        }
                    },
                    {
                        type: 'text',
                        text: '总结一下这个PDF文档的内容'
                    }
                ]
            }
        ],
        stream: true,
        stream_options: { include_usage: true },
        // 需要开启该参数才会在 usage 中返回 x_tools.pdf_page_parser.count(PDF解析页数)
        include_tool_usage: true
    });

    for await (const chunk of stream) {
        if (!chunk.choices?.length) {
            console.log('\nUsage:', chunk.usage);
            continue;
        }
        const delta = chunk.choices[0].delta;
        if (delta.content) {
            process.stdout.write(delta.content);
        }
    }
}

main();

HTTP

Sample Code

# 以下为新加坡地域的URL,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的URL不同。
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen4-max",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "file",
                    "file": {
                        "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
                    }
                },
                {
                    "type": "text",
                    "text": "总结一下这个PDF文档的内容"
                }
            ]
        }
    ],
    "stream": true,
    "stream_options": {
        "include_usage": true
    },
    "include_tool_usage": true
}'

DashScope

Python

Sample Code

import os
from dashscope import MultiModalConversation
import dashscope

# 以下为新加坡地域的URL,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的URL不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

messages = [
    {
        "role": "user",
        "content": [
            {
                "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
            },
            {
                "text": "总结一下这个PDF文档的内容"
            }
        ]
    }
]

completion = MultiModalConversation.call(
    # 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key = "sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen4-max",
    messages=messages,
    stream=True,
    incremental_output=True
)

for chunk in completion:
    message = chunk.output.choices[0].message
    if message.content:
        print(message.content[0]["text"], end="", flush=True)

HTTP

Sample Code

# 以下为新加坡地域的URL,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的URL不同。
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-SSE: enable" \
-d '{
    "model": "qwen4-max",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
                    },
                    {
                        "text": "总结一下这个PDF文档的内容"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "incremental_output": true,
        "result_format": "message"
    }
}'

Responses API

The Responses API supports passing PDFs via input_file.file_url. qwen3.8-27b does not support this method.

The following examples use the workspace-specific domain of the Beijing region. Replace {WorkspaceId}, and configure the corresponding API Key and domain according to your selected region and deployment scope. For more information, see Access information.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
    timeout=300.0,
)

response = client.responses.create(
    model="qwen3.8-flash",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_file", "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"},
            {"type": "input_text", "text": "总结这个PDF文档的内容。"},
        ],
    }],
    extra_body={"include_tool_usage": True},
)

print(response.output_text)
curl 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-flash",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_file", "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"},
        {"type": "input_text", "text": "总结这个PDF文档的内容。"}
      ]
    }],
    "include_tool_usage": true
  }'

Anthropic

qwen3.8-max, qwen3.8-flash, and qwen4 series models support passing PDF file URLs directly through the Anthropic-compatible Messages API. In messages[].content, use a type: "document" content block, set source.type to url, and specify the PDF file URL in source.url.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1/messages' \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $DASHSCOPE_API_KEY" \
  --data '{
    "model": "qwen3.8-max",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "document",
          "source": {
            "type": "url",
            "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
          }
        },
        {"type": "text", "text": "总结一下这个PDF文档的内容"}
      ]
    }]
  }'

Anthropic-compatible Messages

Use Base64 input

If you cannot provide the file's URL address, you can also pass the PDF file as a Base64-encoded string. When using file_data, the filename field is required.

NoteBase64 encoding increases the data size by about 1/3. For example, a 150MB file becomes about 200MB after encoding, which exceeds the request body size limit. For large files, use the URL method instead.

Chat Completions / DashScope

import base64
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为新加坡地域的URL,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# 读取并编码PDF文件
with open("report.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "file",
                    "file": {
                        "file_data": f"data:application/pdf;base64,{pdf_base64}",
                        "filename": "report.pdf"
                    }
                },
                {
                    "type": "text",
                    "text": "这份报告的核心结论是什么?"
                }
            ]
        }
    ]
)

print(completion.choices[0].message.content)
import base64
import os
from dashscope import MultiModalConversation
import dashscope

# 以下为新加坡地域的URL,调用时请将 {WorkspaceId} 替换为真实的业务空间ID,各地域的URL不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

# 读取并编码PDF文件
with open("report.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

messages = [
    {
        "role": "user",
        "content": [
            {
                "file_data": f"data:application/pdf;base64,{pdf_base64}",
                "filename": "report.pdf"
            },
            {
                "text": "这份报告的核心结论是什么?"
            }
        ]
    }
]

response = MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen4-max",
    messages=messages
)

print(response.output.choices[0].message.content[0]["text"])

Anthropic

The Anthropic-compatible API also supports Base64 PDF input. qwen3.8-max, qwen3.8-flash, and qwen4 series models support passing PDF file URLs directly through the Anthropic-compatible Messages API. In messages[].content, use a type: "document" content block, set source.type to url, and specify the PDF file URL in source.url.

The Anthropic-compatible API supports passing Base64 PDFs via document.source. Download the sample PDF and save it as report.pdf, or replace it with your own PDF file. The Python example requires the anthropic SDK to be installed.

The following examples use the workspace-specific domain of the Beijing region. Replace {WorkspaceId}, and configure the corresponding API Key and domain according to your selected region and deployment scope. For more information, see Access information.

import os
import base64
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic",
    timeout=300.0,
)

with open("report.pdf", "rb") as file:
    pdf_base64 = base64.b64encode(file.read()).decode("utf-8")

response = client.messages.create(
    model="qwen3.8-flash",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_base64,
                },
            },
            {"type": "text", "text": "总结这个PDF文档的内容。"},
        ],
    }],
    extra_body={"include_tool_usage": True},
)

for block in response.content:
    if block.type == "text":
        print(block.text)
PDF_BASE64=$(base64 < report.pdf | tr -d '\n')
curl 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic/v1/messages' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "model": "qwen3.8-flash",
  "max_tokens": 1024,
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "document",
        "source": {
          "type": "base64",
          "media_type": "application/pdf",
          "data": "$PDF_BASE64"
        }
      },
      {"type": "text", "text": "总结这个PDF文档的内容。"}
    ]
  }],
  "include_tool_usage": true
}
EOF

Request parameters

The following parameter table applies to Chat Completions. The Responses API uses type: "input_file" and file_url; the Anthropic-compatible API uses type: "document" and sets type: "base64", media_type: "application/pdf", and data (a Base64 string without the Data URI prefix) in source. DashScope passes files via elements in the content array that contain file_url or file_data. For URL input, type is required and fixed to document; source is a required object, where type is a required string set to url, and url is a required string specifying the PDF file URL.

NoteIn the protocol, the URL part supports only string input, not the list (array) form.

OpenAI-compatible protocol format:

Parameter

Type

Whether Required

Description

file_url

string

Required (choose one of the two)

The download address of the PDF file. Either this parameter or file_data is required.

file_data

string

The PDF file input in Base64 format, in the format data:application/pdf;base64,xxx. Either this parameter or file_url is required.

filename

string

Conditionally required

The file name. Required when file_data is used as the input parameter.

file_format

string

No

The file format. Optional. Currently only pdf is supported, and the default is pdf.

Limits

Item

Limit

Single file size limit

150MB

Page limit per document

256 pages

NotePDF parsing may take longer than plain text requests. The first-token timeout can be up to 300 s. We recommend using streaming output to obtain results in real time and avoid long waits.

Billing Details

Billing involves the following aspects:

  • Model invocation fees: The text and images parsed from the PDF file are counted toward the model's input tokens and billed at the model's standard input price.
  • Document parsing fees: Billed by the number of parsed PDF pages, with unit prices varying by region: China (Beijing) $0.003/page, Singapore $0.0033/page. Global deployment mode: $0.003/page.

For the input and output unit prices of each model, see Model invocation billing.

View the number of parsed PDF pages

The Responses API of qwen4-max uses the top-level tool_usage of the response, where num_requests of each tool is the number of billable calls, and pdf_page_parser.num_requests is the number of parsed pages. The Responses examples for Qwen3.8 still use usage.x_tools.

Chat Completions and the Responses API (Qwen3.8) can pass in include_tool_usage: true at the top level of the request body and view the number of parsed pages from usage.x_tools.pdf_page_parser.count; for DashScope, view it from usage.plugins.pdf_page_parser.count. The number of parsed pages returned by the Anthropic-compatible API is located at the top level of the response in x_tools.pdf_page_parser.count. If the parsing count is not returned, it does not mean that no parsing fee was incurred for this request.

// 需在请求体顶层传入 "include_tool_usage": true 后才会返回。
// OpenAI Python SDK 请通过 extra_body={"include_tool_usage": True} 传入,
// 直接使用 HTTP/curl 时放在请求体顶层,不要嵌套到 extra_body 或 stream_options。
{
    "usage": {
        "x_tools": {
            "pdf_page_parser": {
                "count": 10,
                "strategy": "normal"
            }
        }
    }
}
// 默认返回,无需额外参数。
{
    "usage": {
        "plugins": {
            "pdf_page_parser": {
                "count": 10,
                "strategy": "normal"
            }
        }
    }
}
{
    "x_tools": {
        "pdf_page_parser": {
            "count": 10,
            "strategy": "normal"
        }
    }
}