Document Rendering

Document Rendering is a critical aspect of FastPDF — it enables the conversion and display of various file formats in a manner suitable for your application. On this page, we’ll explore the diverse document rendering endpoints you can leverage to manage file transformations programmatically. We will delve into how to query, create, update, and delete renderings for a multitude of document types.

This endpoint allows you to render a PDF file using a specific template. It supports multiple template formats such as docx, xlsx, pptx, html, odt, ods, and odp. The system uses mustache templating for the rendering process. If you want to render images within your template, you can use the provided syntax: <image src="{{image_uri}}">.

Rendering a document involves a two-step process. Firstly, you must add a template to your FastPDF dashboard. This template will serve as the layout for your document. Once you have a template in place, you can render a document by specifying the template's id along with any necessary rendering data and options.

Alternatively, if you are not concerned about re-uploading your template for each render, you can opt for a more direct approach. By using the immediate rendering endpoint, you can directly render your document without having to add and manage templates.

Render Options

The Render Options model contains all the information necessary for rendering a document or an image. It allows for customization, from the barcode's size and location, to its margins and scaling, and even whether to include text or maintain the original aspect ratio.

Not all properties have effect on every calls. Certain options only affects PDF rendering, barcode generation and/or image rendering.

Properties

  • Name
    display_header_footer
    Type
    bool
    Description

    A flag indicating whether to display headers and footers. (Default: true)

  • Name
    header_file
    Type
    bytes
    Description

    The binary content of the header file.

  • Name
    footer_file
    Type
    bytes
    Description

    The binary content of the footer file.

  • Name
    paper_format
    Type
    string
    Description

    The paper format for PDF rendering. Supported formats include Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6. (Default: A4).

  • Name
    landscape
    Type
    boolean
    Description

    A boolean value indicating if the PDF rendering should be in landscape orientation (true) or portrait (false). (Default: false).

  • Name
    margin_top
    Type
    integer
    Description

    The top margin for PDF rendering in cm. (Default: 2).

  • Name
    margin_bottom
    Type
    integer
    Description

    The bottom margin for PDF rendering in cm. (Default: 2).

  • Name
    margin_left
    Type
    integer
    Description

    The left margin for PDF rendering in cm. (Default: 1).

  • Name
    margin_right
    Type
    integer
    Description

    The right margin for PDF rendering in cm. (Default: 1).

  • Name
    scale
    Type
    float
    Description

    The scale for PDF rendering. Allowed value range from 0.1 to 2.0.

  • Name
    background
    Type
    boolean
    Description

    A boolean value indicating if background should be printed in PDF rendering. Mostly affects CSS property such as background-color, background-image, etc. (Default: true).

  • Name
    page_range
    Type
    string
    Description

    The page range for PDF rendering.

  • Name
    page_number_footer_enabled
    Type
    boolean
    Description

    A boolean value indicating whether or not page numbers should be included in the footer during PDF rendering. (Default: true).

  • Name
    date_header_enabled
    Type
    boolean
    Description

    A boolean value indicating whether or not today's date should be included in the header during PDF rendering. (Default: true).

  • Name
    date_locale
    Type
    string
    Description

    A string indicating the locale for the header date. Available locales: en_US, en_GB, zh_CN, ja_JP, fr_FR, de_DE, es_ES, pt_BR, ru_RU, ar_EG, hi_IN, it_IT (Default: en_US).

  • Name
    title_header_enabled
    Type
    boolean
    Description

    A boolean value indicating whether or not title should be included in the header during PDF rendering. (Default: true).

  • Name
    x
    Type
    float
    Description

    The x-coordinate for positioning images or barcodes.

  • Name
    y
    Type
    float
    Description

    The y-coordinate for positioning images or barcodes.

  • Name
    w
    Type
    float
    Description

    The width for images or barcodes. You can also use width.

  • Name
    h
    Type
    float
    Description

    The height for images or barcodes. You can also use height.

  • Name
    keep_ratio
    Type
    bool
    Description

    A flag indicating whether to maintain the original aspect ratio of images or barcodes. (Default: true)

  • Name
    text_enabled
    Type
    bool
    Description

    A flag indicating whether to include text for images or barcodes.

  • Name
    image_mode
    Type
    string
    Description

    Specifies the mode of the image. Here are the possibilities: BW, L, P, RGB, RGBA, CMYK, YCbCr, LAB, HSV, I, F, LA, PA, RGBX, RGBa, La, I_16, I_16L, I_16B, I_16N, BGR_15, BGR_16, BGR_24.

  • Name
    compress
    Type
    bool
    Description

    A flag indicating whether to compress the rendered output.

  • Name
    transparency_enabled
    Type
    bool
    Description

    A flag indicating whether to enable transparency for the rendered output.

  • Name
    background_color
    Type
    tuple
    Description

    The RGB tuple for the background color.

  • Name
    templating_engine
    Type
    string
    Description

    The templating engine used for rendering. Allowed value: jinja2, flask. (Default: jinja2)

  • Name
    rendering_engine
    Type
    string
    Description

    The rendering engine used for generating the final output. Allowed value: chrome, webkit. (Default: chrome)

Example payload

{
  "display_header_footer": true,
  "landscape": false,
  "paper_format": "A4",
  "background": true,
  "margin_top": 2,
  "margin_right": 1,
  "margin_bottom": 2,
  "margin_left": 1,
  "page_number_footer_enabled": true,
  "title_header_enabled": false,
  "date_header_enabled": true
}
POST/v1/render/pdf/{template_id}

Template to PDF

This endpoint allows you to render a template using the provided render data and options.

Required attributes

  • Name
    template_id
    Type
    string
    Description

    The unique identifier of the template to be rendered.

  • Name
    render_data
    Type
    Description

    The data required for rendering the template, formatted either as a data object (see example below), or as a string path to a file containing a JSON object.

Optional attributes

  • Name
    render_options
    Type
    RenderOptions
    Description

    The options for rendering the template. Any render option specified here will overwrite the render options already registered with the template.

Request

POST
/v1/render/{format_type}/{template_id}
curl -X POST https://data.fastpdfservice.com/v1/render/{format_type}/{template_id} \
  -H "Authorization: {token}" \
  -d 'render_data={render_data_json}' \
  -d 'render_options={render_options_json}'
POST/v1/render/{format_type}/batch/{template_id}

Template to many PDFs

This endpoint allows you to render a template multiple times at once, from a list of render data objects using the same render options.

The output PDFs are returned in a zip file.

Required attributes

  • Name
    template_id
    Type
    string
    Description

    The unique identifier of the template to be rendered.

  • Name
    render_data
    Type
    Description

    The data required for rendering the template, formatted either as a list of data object (see example below), or as a string path to a file containing a JSON array, or to a csv file, or a xls or xlsx file.

    Supported formats: JSON array, csv, xls, xlsx.

Optional attributes

  • Name
    render_options
    Type
    RenderOptions
    Description

    The options for rendering the template. Any render option specified here will overwrite the render options already registered with the template.

Request

POST
/v1/render/{format_type}/batch/{template_id}
curl -X POST https://data.fastpdfservice.com/v1/render/{format_type}/batch/{template_id} \
  -H "Authorization: {token}" \
  -d 'render_data={render_data_json}' \
  -d 'render_options={render_options_json}'
POST/v1/render/image/{image_id}

Image to PDF

This endpoint allows you to render an image to PDF format using an image ID. This endpoint requires to add an image beforehand, otherwise use the Image To PDF immediately method.

Path parameters

  • Name
    image_id
    Type
    string
    Description

    The ID of the image to render.

    Supported formats: jpeg, png, gif, bmp, tiff, webp, svg, ico, psd, ai, eps, cr2, nef, sr2, orf, rw2, dng, arw, and heic.

Optional parameters

  • Name
    render_options
    Type
    RenderOptions
    Description

    The options for rendering the image.

Request

GET
/v1/img/{image_id}
curl -X GET https://data.fastpdfservice.com/v1/img/{image_id} \
  -H "Authorization: {token}" \
  -d "render_options={render_options_json}"
POST/v1/render/img

Image to PDF immediately

This endpoint allows you to render an image to PDF format.

Required attributes

  • Name
    image
    Type
    File
    Description

    The image file to be converted. Can be a path to the image, BytesIO, or bytes.

    Supported formats: jpeg, png, gif, bmp, tiff, webp, svg, ico, psd, ai, eps, cr2, nef, sr2, orf, rw2, dng, arw, and heic.

Optional attributes

  • Name
    render_options
    Type
    RenderOptions
    Description

    The options for rendering the image.

Request

POST
/v1/render/img
curl -X POST https://data.fastpdfservice.com/v1/render/img \
  -H "Authorization: {token}" \
  -F "image=@path/to/image.png" \
  -F "render_options={render_options_json}"
POST/v1/render/{format}

Render PDF Immediately

This endpoint allows you to render one document immediately based on the provided data, without prior Template upload.

Required attributes

  • Name
    file_data
    Type
    File
    Description

    The template content. It can be a string path to a file, or a template string in bytes (see examples below).

Optional attributes

  • Name
    template_data
    Type
    Template
    Description

    The template data as a Template object. If not provided, a default template is used.

  • Name
    render_data
    Type
    Description

    The data to populate the template with. Can be a dict or a JSON string.

  • Name
    header_data
    Type
    File
    Description

    The header content file. Can be a path to the file, BytesIO, or bytes.

  • Name
    footer_data
    Type
    File
    Description

    The footer content file. Can be a path to the file, BytesIO, or bytes.

  • Name
    render_options
    Type
    RenderOptions
    Description

    The rendering options as a RenderOptions object.

Request

POST
/v1/render/{format}
curl -X POST https://data.fastpdfservice.com/v1/render/{format} \
  -H "Authorization: {token}" \
  -F "file_data=@path/to/file.html" \
  -F "template_data={template_data_json}" \
  -F "render_data={render_data_json}" \
  -F "header_data=@path/to/header.html" \
  -F "footer_data=@path/to/footer.html" \
  -F "render_options={render_options_json}"
POST/v1/render/{format}/batch

Render many PDF Immediately

This endpoint allows you to render multiple documents based on the provided data and template, without prior template upload.

Required attributes

  • Name
    file_data
    Type
    File
    Description

    The template content. It can be a string path to a file, or a template string in bytes (see examples below).

Optional attributes

  • Name
    template_data
    Type
    Template
    Description

    The template data as a Template object. If not provided, a default template is used.

  • Name
    render_data
    Type
    Description

    The data required for rendering the template, formatted either as a list of data object (see example below), or as a string path to a file containing a JSON array, or to a csv file, or a xls or xlsx file.

    Supported formats: JSON array, csv, xls, xlsx.

  • Name
    header_data
    Type
    File
    Description

    The header content file. Can be a path to the file, BytesIO, or bytes.

  • Name
    footer_data
    Type
    File
    Description

    The footer content file. Can be a path to the file, BytesIO, or bytes.

  • Name
    render_options
    Type
    RenderOptions
    Description

    The rendering options as a RenderOptions object.

Request

POST
/v1/render/{format}/batch
curl -X POST https://data.fastpdfservice.com/v1/render/{format}/batch \
  -H "Authorization: {token}" \
  -F "file_data=@path/to/file.html" \
  -F "template_data={template_data_json}" \
  -F "render_data={render_data_list_json}" \
  -F "header_data=@path/to/header.html" \
  -F "footer_data=@path/to/footer.html" \
  -F "render_options={render_options_json}"