Document Parsing API

The Document Parsing API provides two synchronous endpoints for one-time PDF or image uploads. A file is stored temporarily on the Studio host and deleted after the request succeeds or fails. Results are returned directly in the HTTP response; the API does not create a knowledge base document, write to Milvus, or upload figures to knowledge base object storage.

Prerequisites and authentication

An administrator must configure a runtime-ready VLM parser model under Admin panel → System Models → UnieAI VLM parser. The caller's API key must be valid and able to use that model.

Create a key under Workspace → API keys and send it as a Bearer token:

Authorization: Bearer sk-your-api-key

VLM calls made during parsing use this key, and usage and billing follow the key's workspace. Never expose the key in browser-side code.

Parse a PDF

curl -X POST "https://your-studio.example/api/parse/pdf" \
  -H "Authorization: Bearer $UNIEAI_API_KEY" \
  -F "file=@document.pdf;type=application/pdf"

Successful response:

{
  "request_id": "req_abc123",
  "data": {
    "source_kind": "pdf",
    "page_count": 2,
    "pages": [
      {
        "pageIndex": 0,
        "content": "",
        "summaryContent": "# Q1 report\nRevenue increased...",
        "figures": [
          {
            "type": "chart",
            "bbox": [100, 180, 900, 720],
            "description": "A bar chart of monthly revenue",
            "language": "en",
            "visibleText": "January February March"
          }
        ]
      }
    ],
    "metadata": {
      "engine": "parser_cli",
      "vlm_model": "configured-model-slug",
      "file_name": "document.pdf",
      "file_size": 123456
    }
  }
}

• content comes from parser rawText or content and can be empty in the current VLM PDF path.
• summaryContent is the primary VLM page transcription.
• bbox uses normalized 0–1000 coordinates.
• vlm_model is the administrator-configured model slug, not a fixed model name.
• The API returns figure text and coordinates, not crop files, Base64 data, or image URLs.

Optional chunks

Only the PDF endpoint supports the chunk query parameter, and only the exact value chunk=true enables it:

curl -X POST "https://your-studio.example/api/parse/pdf?chunk=true" \
  -H "Authorization: Bearer $UNIEAI_API_KEY" \
  -F "file=@document.pdf;type=application/pdf"

The response data then also contains:

{
  "chunks": [
    {
      "chunkIndex": 0,
      "pageIndex": 0,
      "content": "# Q1 report\nRevenue increased...",
      "sectionTitle": "Q1 report",
      "chunkingStrategy": "line_based"
    }
  ]
}

These chunks exist only in this response. The option does not persist the document, generate embeddings, write Dense/BM25 indexes, or run Contextual Retrieval. The actual chunkingStrategy depends on parser output and the synchronous chunking path.

Parse an image

curl -X POST "https://your-studio.example/api/parse/image" \
  -H "Authorization: Bearer $UNIEAI_API_KEY" \
  -F "file=@screenshot.png;type=image/png"

Successful response:

{
  "request_id": "req_def456",
  "data": {
    "source_kind": "image",
    "content": "Extracted text and visual description...",
    "figures": [
      {
        "type": "diagram",
        "bbox": [50, 100, 950, 880],
        "description": "A system architecture diagram",
        "language": "en",
        "visibleText": "Client API Runtime"
      }
    ],
    "metadata": {
      "engine": "parser_cli",
      "vlm_model": "configured-model-slug",
      "file_name": "screenshot.png",
      "file_size": 456789
    }
  }
}

The image endpoint does not support chunk=true. If the VLM detects no individual visual region, the parser may attempt to treat the whole image as a photo and caption it.

Error shape

{
  "error": {
    "code": "invalid_request",
    "message": "Missing 'file' field in form data",
    "request_id": "req_err789"
  }
}

The route does not fully verify that the extension, MIME type, and file bytes agree before invoking the parser. Send PDFs to the PDF endpoint and images to the image endpoint with an accurate filename and content type.

Deployment and usage limits

• Five and two minutes are parser-process timeouts. A reverse proxy, CDN, or hosting platform may enforce a shorter request timeout or body-size limit.
• This is a synchronous API, so the connection must remain open until parsing finishes. Use knowledge base background ingestion for large or multi-page documents.
• The configured VLM receives document pages or images. Before using an external model service, review data residency, retention, confidentiality, and personal-data requirements.
• Transcriptions and captions are model-generated. Validate numbers, tables, legends, and domain-specific terms when exactness matters.

Use from an agent or backend service

An agent tool cannot send only a file_url JSON value to these endpoints. A trusted backend must download and validate the file, then construct the multipart request. Restrict source domains, download size, redirects, and private network addresses to reduce SSRF risk.

Related documentation