Skip to main content

PDF understanding

Analise textos e imagens em documentos PDF com Chat Completions, Responses API, DashScope ou a API compatível com Anthropic.

Modelos compatíveis

qwen4-max , qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-27b A compreensão de PDF com qwen3.8-27b está disponível apenas pelo Chat Completions ou DashScope em Beijing.

Início rápido

Os exemplos a seguir demonstram como enviar um arquivo PDF para o modelo.
É necessário ter Obtenha uma chave de API e ter concluído Configure a chave de API como uma variável de ambiente .
  • OpenAI Compatible
  • DashScope
  • Responses API
  • Python
  • Node.js
  • HTTP

Código de exemplo

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 China (Pequim) region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
    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": "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)

Enviar uma URL de PDF pela API compatível com Anthropic

Os modelos qwen3.8-max, qwen3.8-flash e da série qwen4 aceitam URLs de arquivos PDF pela Messages API compatível com Anthropic. Em messages[].content, use um bloco de conteúdo type: "document", defina source.type como url e especifique a URL do arquivo PDF em source.url. Este exemplo usa a região de Singapura. Substitua {WorkspaceId} pelo ID do seu espaço de trabalho e defina a variável de ambiente DASHSCOPE_API_KEY com sua chave de API do Model Studio.
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文档的内容"}
      ]
    }]
  }'
Messages compatível com Anthropic

Uso de entrada Base64

Se não for possível fornecer uma URL, envie o arquivo PDF como uma string codificada em Base64. O campo filename é obrigatório ao usar file_data.
A codificação Base64 aumenta o tamanho dos dados em aproximadamente um terço. Por exemplo, um arquivo de 150 MB passa para cerca de 200 MB após a codificação, o que excede o limite de tamanho do corpo da requisição. Para arquivos grandes, use o método de URL.
  • Chat Completions / DashScope
  • Anthropic
import base64
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. Replace {WorkspaceId} with your actual workspace ID when calling the API. URLs differ by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.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="qwen4-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)

Parâmetros da requisição

A tabela de parâmetros a seguir se aplica a Chat Completions. A Responses API usa type: "input_file" e file_url. A API compatível com Anthropic usa type: "document" com source.type: "base64", source.media_type: "application/pdf" e source.data (string Base64 sem prefixo Data URI). O DashScope aceita arquivos como itens no array content contendo file_url ou file_data. Para entrada por URL, type é obrigatório e tem o valor fixo document; source é um objeto obrigatório. Dentro de source, type é uma string obrigatória definida como url, e url é uma string obrigatória que contém a URL do arquivo PDF.
O campo URL aceita apenas uma string. Não há suporte para lista (array) de URLs.
Formato compatível com OpenAI:

Parâmetro

Tipo

Obrigatório

Descrição

file_urlstringCondicionalURL do arquivo PDF para download. Mutuamente exclusivo com file_data.
file_datastringCondicionalDados do PDF codificados em Base64 no formato data:application/pdf;base64,.... Mutuamente exclusivo com file_url.
filenamestringCondicionalNome do arquivo. Obrigatório ao usar file_data.
file_formatstringNãoFormato do arquivo. Atualmente, há suporte apenas para pdf. O padrão é pdf.

Limites

Item

Limite

Tamanho máximo do arquivo150 MB
Contagem máxima de páginas256 páginas
A análise de PDF pode levar mais tempo do que requisições de texto comuns. O tempo limite para o primeiro token é de até 300 segundos. Recomendamos usar saída em streaming para evitar longas esperas.

Faturamento

O faturamento inclui os seguintes itens:
  • Tokens de entrada do modelo: O texto extraído do PDF e as imagens analisadas das páginas são contabilizados como tokens de entrada e cobrados à taxa padrão de tokens de entrada do modelo.
  • Taxa de análise de documento: Cobrada por página do documento PDF analisado, correspondente ao item de medição document_parsing (pdf). Os preços unitários variam por região: China (Beijing): $0,003 por página, Singapura: $0,0033 por página. Modo de implantação global: USD 0,003 por página.

Ver contagem de páginas PDF analisadas

Para Responses com qwen4-max, use tool_usage no nível superior da resposta. O campo num_requests de cada ferramenta indica as solicitações cobradas; pdf_page_parser.num_requests indica as páginas analisadas. Os exemplos de Responses do Qwen3.8 usam usage.x_tools. Em Chat Completions e na Responses API (Qwen3.8), envie include_tool_usage: true no nível superior do corpo da requisição e leia usage.x_tools.pdf_page_parser.count. No DashScope, leia usage.plugins.pdf_page_parser.count. A API compatível com Anthropic retorna a contagem no campo de nível superior da resposta x_tools.pdf_page_parser.count. A ausência da contagem não significa que nenhuma taxa de análise foi cobrada.
Anthropic
{
    "x_tools": {
        "pdf_page_parser": {
            "count": 10,
            "strategy": "normal"
        }
    }
}