Documentação da API PaddleOCR — análise para Markdown e JSON

Visão geral

Crie uma tarefa por arquivo ou URL, pesquise seu status e baixe o ZIP. As solicitações são assíncronas. Pro Mensal e Pro Anual suportam API; Grátis não.

https://YOUR_API_HOST/api/open/v1

Substitua YOUR_API_HOST pelo seu domínio API. Todos os caminhos abaixo usam este URL base. Os exemplos usam IDs de espaço reservado e URLs assinados.

Autenticação

Envie Authorization: Bearer seguido pela sua chave Pro API em cada solicitação API. Obtenha ou redefina a chave usando o botão de chave API. As chaves diferenciam maiúsculas de minúsculas: sk- plus 24 letras e dígitos aleatórios. Os JWTs de login do usuário não autenticam esses endpoints.

Authorization: Bearer sk-YOUR_API_KEY

Mantenha a chave no seu servidor. Não o exponha em frontend público code, repositórios ou solicitações de download. Os downloads usam seu próprio URL assinado. A redefinição da chave invalida imediatamente a chave antiga; O acesso API também requer uma assinatura Pro ativa.

Início rápido

Substitua o host API, defina MINERU_API_KEY e forneça paper.pdf. Esses exemplos são carregados uma vez, pesquisados ​​a cada 3 segundos por até 30 minutos e, em seguida, transmitidos ZIP para o disco. O tempo limite de sondagem é um limite do cliente e não cancela a tarefa do servidor. Use o ID da tarefa para continuar consultando. Python precisa do pacote requests; Node.js precisa da versão 20+; cURL usa Bash e jq.

# pip install requests
import os
import time
import requests

API = "https://YOUR_API_HOST/api/open/v1"
headers = {"Authorization": "Bearer " + os.environ["MINERU_API_KEY"]}
with open("paper.pdf", "rb") as source:
    response = requests.post(API + "/tasks", headers=headers, files={"file": ("paper.pdf", source, "application/pdf")},
        data={"force_ocr": "true", "extra_formats": '["docx","html"]'}, timeout=120)
response.raise_for_status()
body = response.json()
if body["code"] != 0:
    raise RuntimeError(body["code"] + ": " + body["msg"])
task_id = body["data"]["task_id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    response = requests.get(API + "/tasks/" + task_id, headers=headers, timeout=30)
    response.raise_for_status()
    body = response.json()
    if body["code"] != 0:
        raise RuntimeError(body["code"] + ": " + body["msg"])
    data = body["data"]
    task = data["task"]
    if task["status"] == "completed":
        url = data["results"].get("full_zip_url")
        if not url:
            raise RuntimeError("ZIP unavailable; check expires_at")
        # Download separately: do not send the API key to the download host.
        with requests.get(url, stream=True, timeout=120) as download:
            download.raise_for_status()
            with open("result.zip", "wb") as output:
                for chunk in download.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.zip")
        break
    if task["status"] in {"failed", "expired"}:
        raise RuntimeError(task["status"] + ": " + task["error"])
    time.sleep(3)
else:
    raise TimeoutError("Polling timed out; task ID: " + task_id)

Criar uma tarefa

Um terminal: POST /api/open/v1/tasks. Escolha um método de entrada: carregue um arquivo usando multipart/form-data ou envie source_url usando JSON. Ambos retornam data.task_id para o mesmo fluxo de consulta de tarefa. Cada envio aceito cria uma nova tarefa.

O modo químico aceita apenas PDF e imagens. force_ocr e extra_formats não estão disponíveis.

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -F '[email protected]' \
  -F 'force_ocr=true' \
  -F 'extra_formats=["docx","html"]'

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"source_url":"https://example.com/paper.pdf","force_ocr":true,"extra_formats":["docx","html"]}'

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -F '[email protected]' \
  -F 'parse_type=1'

Listar tarefas

Lista suas tarefas da web e API juntas, as mais recentes primeiro. Os itens contêm apenas task_id, status, credits, created_at e nome de arquivo, tamanho, mime_type e source_type. Consulte detalhes de metadados de arquivo, motivo da falha, expiração e URLs de resultado. page_size aceita 1–100; valores inválidos padrão para 20. página abaixo 1 padrão para 1.

Parâmetros de consulta

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks?page=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

Campos de resposta · 200 OK

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
        "parse_type": 0,
        "status": "completed",
        "credits": 2,
        "created_at": "2026-10-12T07:04:05Z",
        "file": {
          "name": "paper.pdf",
          "size": 12345,
          "mime_type": "application/pdf",
          "source_type": "upload"
        }
      }
    ],
    "has_more": false,
    "page": 1,
    "page_size": 20
  }
}

TaskSummary

Obter tarefa results

Leia data.task.status. results é sempre um dicionário: vazio para queued, running, failed ou expired e contém URLs de documentos quando completed. O URL ZIP é results.full_zip_url. Tarefas com falha retornam HTTP 200 com code task_failed e o motivo em msg; expired results use code result_expired.

Parâmetros de caminho

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Campos de resposta · 200 OK

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "running",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {}
  }
}

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "completed",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {
      "original_url": "https://downloads.example.com/uploads/4001a517-cd93-47a6-a56a-e53d2a0828df/aa0e6ab6-44f3-4554-b459-b62fe4c6b437.pdf?token=SIGNED_TOKEN",
      "markdown_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/markdown.md?token=SIGNED_TOKEN",
      "middle_json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/middle_json.json?token=SIGNED_TOKEN",
      "structured_json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/structured_content.json?token=SIGNED_TOKEN",
      "images": {
        "images/001.jpg": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/images/001.jpg?token=SIGNED_TOKEN"
      },
      "full_zip_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/exports/6b0e6ab6-44f3-4554-b459-b62fe4c6b439.zip?token=SIGNED_TOKEN"
    }
  }
}

{
  "code": "task_failed",
  "msg": "MinerU job ended: failed",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "failed",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "MinerU job ended: failed",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {}
  }
}

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 1,
      "status": "completed",
      "credits": 2,
      "force_ocr": false,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {
      "original_url": "https://downloads.example.com/uploads/4001a517-cd93-47a6-a56a-e53d2a0828df/aa0e6ab6-44f3-4554-b459-b62fe4c6b437.pdf?token=SIGNED_TOKEN",
      "json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/molecular_structures.json?token=SIGNED_TOKEN"
    }
  }
}

Task

File

results

Formatos e limites

Limites Pro: 200 MiB por documento, 50 MiB por imagem e 500 unidades faturáveis. API e a web compartilham 5 diariamente mais 1,000 unidades mensais, usando primeiro as unidades diárias. O uso é reservado após a validação e cobrado quando o resultado da análise base é salvo. Falha de análise confirmada ou rescisão libera reservas. A falha na publicação/export não reembolsa a análise bem-sucedida; failed ou a execução expirada libera automaticamente as reservas não cobradas. As exportações não voltam a cobrar.

O formato de upload é determinado pela extensão do nome do arquivo, sem distinção entre maiúsculas e minúsculas. PDF, PowerPoint e Excel devem ter metadados de página/unit legíveis. MIME não é usado para validar conteúdos carregados. Arquivos vazios, extensões não suportadas, PDFs criptografados ou ilegíveis e entradas acima do limite são rejeitados. A análise HTML é estática e não executa JavaScript. 1 MiB = 1,048,576 bytes.

Estados da tarefa

Continue pesquisando queued ou running. Baixe em completed; leia error e pare em failed. expired significa que a retenção terminou. status descreve toda a tarefa; As tarefas API são concluídas somente quando a ZIP final estiver pronta.

ZIP results e downloads

O API produz um ZIP final. Markdown, Médio JSON, estruturado JSON e imagens salvas são incluídos por padrão. extra_formats suporta apenas html, docx e latex; os arquivos solicitados são adicionados ao mesmo ZIP. Não crie um trabalho de exportação da Web separado para uma tarefa API. Sem extras significa que results.full_zip_url aponta para base.zip; extras significam que aponta para o arquivo exports/a ZIP.

Tarefas químicas retornam results.original_url e results.json_url, sem ZIP ou exportações adicionais.

O resultado químico é um array JSON com todos os campos nativos do MolParser por molécula. Sem moléculas, retorna [].

source, input_index, page_index, bbox, confidence, raw_caption, caption, smi, esmi, cxsmiles, markush, sru, groups

result.zip
├── markdown.md
├── middle_json.json
├── structured_content.json
├── images/
│   └── …
├── model_output.json       (optional)
├── result.html             (extra_formats: html)
├── result.docx             (extra_formats: docx)
└── result.tex              (extra_formats: latex)

Os resultados são mantidos por 7 dias. results.full_zip_url é assinado por no máximo 15 minutos e nunca além da retenção. Baixe com um GET simples, sem Authorization. Se a assinatura expirar enquanto ainda estiver retida, consulte os detalhes novamente para obter um novo URL. Os links de imagens de visualização duram no máximo 2 horas; outros links de arquivos duram no máximo 15 minutos.

Os documentos ZIP mantêm referências de imagens relativas nativas e incluem imagens salvas, portanto, essas referências não dependem de assinaturas CDN. Extraia todo o arquivo e mantenha sua estrutura de pastas. Imagens remotas referenciadas pela entrada HTML não são arquivadas automaticamente e ainda podem apontar para o site de origem.

Erros e recuperação

code 0 indica sucesso. Um code diferente de zero identifica a categoria do erro; msg explica o motivo. Consultas de tarefas com falha ou expiradas retornam HTTP 200 com task_failed ou result_expired e um objeto results vazio.

{
  "code": "quota_exceeded",
  "data": null,
  "msg": "not enough available pages/units"
}