PDF Understanding enables the model to parse and comprehend PDF documents, extracting text and images for analysis. You can pass PDF files via URL or Base64 encoding.
PDF understanding is currently available only in China (Beijing), and calls via the Responses API are not supported at this time.
Supported Models
qwen3.8-max
Quick Start
The following examples demonstrate how to send a PDF file to the model.
You must have Obtain an API key and completed Configure API key as an environment variable.
OpenAI Compatible
Python
Sample Code
from openai import OpenAI
import os
client = OpenAI(
# If the environment variable is not configured, replace with: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the URL for the Beijing (China) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3.8-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": "Summarize this PDF document"
}
]
}
],
stream=True,
stream_options={"include_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({
// If the environment variable is not configured, replace with: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// The following is the URL for the Beijing (China) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
baseURL: 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1'
});
async function main() {
const stream = await openai.chat.completions.create({
model: 'qwen3.8-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: 'Summarize this PDF document'
}
]
}
],
stream: true,
stream_options: { include_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
# The following is the URL for the Beijing (China) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-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": "Summarize this PDF document"
}
]
}
],
"stream": true,
"stream_options": {
"include_usage": true
}
}'DashScope
Python
Sample Code
import os
from dashscope import MultiModalConversation
import dashscope
# The following is the URL for the Beijing (China) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.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": "Summarize this PDF document"
}
]
}
]
completion = MultiModalConversation.call(
# If the environment variable is not configured, replace with: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen3.8-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
# The following is the URL for the Beijing (China) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
curl -X POST "https://{WorkspaceId}.cn-beijing.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": "qwen3.8-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": "Summarize this PDF document"
}
]
}
]
},
"parameters": {
"incremental_output": true,
"result_format": "message"
}
}'Using Base64 Input
If you cannot provide a URL, you can pass the PDF file as a Base64-encoded string. The filename field is required when using file_data.
OpenAI Compatible
import base64
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the URL for the Beijing (China) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)
# Read and encode the PDF file
with open("report.pdf", "rb") as f:
pdf_base64 = base64.b64encode(f.read()).decode("utf-8")
completion = client.chat.completions.create(
model="qwen3.8-max",
messages=[
{
"role": "user",
"content": [
{
"type": "file",
"file": {
"file_data": f"data:application/pdf;base64,{pdf_base64}",
"filename": "report.pdf"
}
},
{
"type": "text",
"text": "What are the key findings in this report?"
}
]
}
]
)
print(completion.choices[0].message.content)DashScope
import base64
import os
from dashscope import MultiModalConversation
import dashscope
# The following is the URL for the Beijing (China) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
# Read and encode the PDF file
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": "What are the key findings in this report?"
}
]
}
]
response = MultiModalConversation.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen3.8-max",
messages=messages
)
print(response.output.choices[0].message.content[0]["text"])Request Parameters
The file input is specified as a content item with type: "file" (OpenAI-compatible) or as a content item containing file_url/file_data (DashScope).
Note
The URL field only accepts a string. A list (array) of URLs is not supported.
OpenAI-compatible format:
|
Parameter |
Type |
Required |
Description |
|
file_url |
string |
Conditional |
URL of the PDF file to download. Mutually exclusive with |
|
file_data |
string |
Conditional |
Base64-encoded PDF data in the format |
|
filename |
string |
Conditional |
The file name. Required when using |
|
file_format |
string |
No |
The file format. Currently only |
Limits
|
Item |
Limit |
|
Maximum file size |
150 MB |
|
Maximum page count |
500 pages |
Note
PDF parsing may take longer than regular text requests. The first token timeout is up to 300 seconds. We recommend using streaming output to avoid long waits.
Billing
Billing involves the following:
-
Model input tokens: Text extracted from the PDF and images parsed from pages are counted as input tokens, billed at the model's standard input token rate.
-
Document parsing fee: Charged per page of the PDF document parsed, corresponding to the metering item document_parsing (pdf).China (Beijing): ¥0.02 per page.
该文章对您有帮助吗？