PDF file understanding via VL model - Alibaba Cloud Model Studio

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 in China (Beijing) and Singapore (qwen3.8-27b supports PDF understanding only in China (Beijing); it is not available in Singapore). Calls via the Responses API are not supported at this time — if you pass a PDF using the Responses API, the call still returns HTTP 200, but the file is not delivered to the model.

Supported Models

qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-27b

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 it with your Model Studio API key: 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},
    # Required to return usage.x_tools.pdf_page_parser.count (PDF parsed page count)
    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({
    // If the environment variable is not configured, replace it with your Model Studio API key: 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 },
        // Required to return usage.x_tools.pdf_page_parser.count (PDF parsed page count)
        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

# 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
    },
    "include_tool_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 it with your Alibaba Cloud Model Studio API key: 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.

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

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

NoteThe 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`.
file_data	string	Conditional	Base64-encoded PDF data in the format `data:application/pdf;base64,...`. Mutually exclusive with `file_url`.
filename	string	Conditional	The file name. Required when using `file_data`.
file_format	string	No	The file format. Currently only `pdf` is supported. Defaults to `pdf`.

Limits

Item	Limit
Maximum file size	150 MB
Maximum page count	256 pages

NotePDF 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). Unit prices vary by region: China (Beijing) ¥0.02 per page, Singapore ¥0.024 per page.

For per-model input and output token prices, see Model inference pricing.

View parsed PDF page count

You can read the parsed PDF page count from the pdf_page_parser.count field under usage in the response. Behavior differs slightly between the two protocols:

OpenAI Compatible

// You must pass "include_tool_usage": true at the top level of the request body.
// With the OpenAI Python SDK, pass it via extra_body={"include_tool_usage": True}.
// With raw HTTP/curl, put it at the top level; do NOT nest it inside extra_body or stream_options.
{
    "usage": {
        "x_tools": {
            "pdf_page_parser": {
                "count": 10,
                "strategy": "normal"
            }
        }
    }
}

DashScope

// Returned by default; no extra parameter is required.
{
    "usage": {
        "plugins": {
            "pdf_page_parser": {
                "count": 10,
                "strategy": "normal"
            }
        }
    }
}