Skip to main content

​
Document Processing API

Tinfoil’s document processing service simplifies parsing diverse document formats — including PDFs, DOCX, PPTX, XLSX, HTML, and images — with sophisticated understanding of document structure, layout, tables, and formulas. Under the hood, Tinfoil uses Docling for document parsing. You can use document processing in two ways:
  • Call /v1/convert/file directly when you want extracted Markdown back from the document service.
  • Send a base64-encoded file through the OpenAI-compatible /v1/responses or /v1/chat/completions APIs. Tinfoil will privately convert supported binary documents to text before forwarding the request to the model.
Current scope: OpenAI-compatible file input support currently accepts base64 file_data only. file_id and the /v1/files upload flow are not supported.

​
1. Convert A Document Directly

The document processing endpoint accepts multipart/form-data requests at /v1/convert/file. Upload a file and the server automatically selects the correct processing pipeline, formats, and OCR settings. 
import { SecureClient } from 'tinfoil'
import fs from 'fs'

const client = new SecureClient()

const fileBuffer = fs.readFileSync('doc.pdf')
const blob = new Blob([fileBuffer], { type: 'application/pdf' })

const formData = new FormData()
formData.append('files', blob, 'doc.pdf')

const response = await client.fetch('/v1/convert/file', {
  method: 'POST',
  body: formData,
})

const result = await response.json()
// result.document.md_content contains the converted Markdown
console.log(result.document.md_content)
The server-side router infers the input format, output format, pipeline, and image/OCR handling from the uploaded file. No additional parameters are required.

​
2. Use File Inputs With The Responses API

If you want OpenAI-compatible file attachments, send a base64-encoded file in an input_file content part on /v1/responses. 
import { SecureClient } from 'tinfoil'
import fs from 'fs'

const client = new SecureClient()
const fileData = fs.readFileSync('doc.pdf').toString('base64')

const response = await client.fetch('/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-oss-120b',
    input: [
      {
        role: 'user',
        content: [
          {
            type: 'input_file',
            filename: 'doc.pdf',
            file_data: `data:application/pdf;base64,${fileData}`,
          },
          {
            type: 'input_text',
            text: 'Summarize this document in 3 bullet points.',
          },
        ],
      },
    ],
  }),
})

const result = await response.json()
console.log(result.output_text)
For binary formats such as PDF, DOCX, PPTX, and images, Tinfoil processes the attachment through the private document-processing backend and injects the extracted content into the model request as text.

​
3. Use File Inputs With Chat Completions

The OpenAI-compatible Chat Completions shape uses type: "file" with a nested file object. 
import { SecureClient } from 'tinfoil'
import fs from 'fs'

const client = new SecureClient()
const fileData = fs.readFileSync('doc.pdf').toString('base64')

const response = await client.fetch('/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-oss-120b',
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'file',
            file: {
              filename: 'doc.pdf',
              file_data: `data:application/pdf;base64,${fileData}`,
            },
          },
          {
            type: 'text',
            text: 'Summarize this document in 3 bullet points.',
          },
        ],
      },
    ],
  }),
})

const result = await response.json()
console.log(result.choices[0].message.content)

​
Attestation

The document upload API uses the same attestation mechanism as other Tinfoil services. Use SecureClient (as shown above) to verify attestation automatically.

Try Private Chat

Experience document upload in our private chat interface with real-time privacy verification.

Docling Project

Learn more about the Docling project and its capabilities for document processing.