Skip to content

O3O DocBuilder and conversion

Format matrix

Input and output formats for conversion, building, template filling and extraction; GET /v1/formats returns the same matrix as JSON.

On this page

DocBuilder groups formats into three families: text (text), spreadsheet (sheet) and presentation (slide). Conversion only happens within one family. The endpoint below returns the current matrix so your program can check before submitting work.

GET/v1/formats

Input and output formats for conversion, building and template filling.

Auth: BearerCommunityEnterprise

Parameters

  • Authorizationheaderrequired
    Bearer <API key or JWT>.
Read the format matrix
curl -sS http://localhost:8080/v1/formats \
  -H "Authorization: Bearer O3O_DEMO_KEY"
const BASE_URL = "http://localhost:8080";
const HEADERS = { Authorization: "Bearer O3O_DEMO_KEY" };

const res = await fetch(`${BASE_URL}/v1/formats`, { headers: HEADERS });
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
console.log(await res.json());
import requests

BASE_URL = "http://localhost:8080"
HEADERS = {"Authorization": "Bearer O3O_DEMO_KEY"}

r = requests.get(f"{BASE_URL}/v1/formats", headers=HEADERS, timeout=30)
if not r.ok:
    raise RuntimeError(f"{r.status_code}: {r.text}")
print(r.json())
<?php
$ch = curl_init("http://localhost:8080/v1/formats");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer O3O_DEMO_KEY"],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    throw new RuntimeException("HTTP $status: " . ($body === false ? curl_error($ch) : $body));
}
print_r(json_decode($body, true));
using System.Net.Http.Headers;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "O3O_DEMO_KEY");

using var res = await http.GetAsync("http://localhost:8080/v1/formats");
if (!res.IsSuccessStatusCode)
    throw new HttpRequestException($"{(int)res.StatusCode}: {await res.Content.ReadAsStringAsync()}");
Console.WriteLine(await res.Content.ReadAsStringAsync());
200families for conversion, build by script type, template for template filling.
{
  "families": {
    "text": {
      "inputs": [
        "docx",
        "doc",
        "odt",
        "rtf",
        "txt",
        "html"
      ],
      "outputs": [
        "docx",
        "odt",
        "rtf",
        "txt",
        "html",
        "pdf",
        "png",
        "jpg"
      ]
    },
    "sheet": {
      "inputs": [
        "xlsx",
        "xls",
        "ods",
        "csv"
      ],
      "outputs": [
        "xlsx",
        "ods",
        "csv",
        "html",
        "pdf",
        "png",
        "jpg"
      ]
    },
    "slide": {
      "inputs": [
        "pptx",
        "ppt",
        "odp"
      ],
      "outputs": [
        "pptx",
        "odp",
        "pdf",
        "png",
        "jpg"
      ]
    }
  },
  "build": {
    "text": [
      "docx",
      "odt",
      "pdf"
    ],
    "sheet": [
      "xlsx",
      "ods",
      "pdf"
    ],
    "slides": [
      "pptx",
      "odp",
      "pdf"
    ]
  },
  "template": {
    "inputs": [
      "docx",
      "odt"
    ],
    "outputs": [
      "docx",
      "odt",
      "pdf"
    ]
  }
}

GET requests are not counted against the limits and work on both plans. Common error: 401 unauthorized.

Conversion: source and target#

Rows are source formats and columns are target formats of POST /v1/convert. ✓ marks a supported pair; a pair marked — returns 415 unsupported_format.

Sourcedocxodtrtftxthtmlpdfxlsxodscsvpptxodppngjpg
docx
doc
odt
rtf
txt
html
xlsx
xls
ods
csv
pptx
ppt
odp
FamilySourceTarget
textdocx, doc, odt, rtf, txt, htmldocx, odt, rtf, txt, html, pdf, png, jpg
sheetxlsx, xls, ods, csvxlsx, ods, csv, html, pdf, png, jpg
slidepptx, ppt, odppptx, odp, pdf, png, jpg

Building documents#

Script typeSave formats
textdocx, odt, pdf
sheetxlsx, ods, pdf
slidespptx, odp, pdf

Template filling#

Template inputOutput
docx, odtdocx, odt, pdf; defaults to the template's own format

Extraction#

The three endpoints /v1/extract/text, /v1/extract/meta and /v1/extract/thumbnail accept every source format in the table above. Text and thumbnail extraction go through an intermediate PDF, so any page of any family can be chosen.

How the source format is detected#

DocBuilder takes the source format from the from parameter; when it is absent, from the extension of filename or of the uploaded file name.

Installed fonts#

The DocBuilder v1 image installs these fonts: Liberation Sans, Liberation Serif, Liberation Mono, Carlito, Caladea, DejaVu Sans, Noto Sans, Noto Serif. Carlito and Caladea are metric-compatible with Calibri and Cambria; Liberation Sans and Liberation Serif are metric-compatible with Arial and Times New Roman, so Office layouts usually hold. All of them cover Vietnamese diacritics.