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文档的内容"}
]
}]
}'
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.
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 | string | The PDF file input in Base64 format, in the format | |
filename | string | Conditionally required | The file name. Required when |
file_format | string | No | The file format. Optional. Currently only |
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"
}
}
}