Response Formats

Understanding the different response formats and how to handle them in your application.

Output Formats

PDFGen Studio supports multiple output formats:

Format	MIME Type	Description
pdf	application/pdf	PDF document (default)
png	image/png	PNG image with transparency support
jpg	image/jpeg	JPEG image (smaller file size)
html	text/html	HTML output (JSON renderer only)

Response Types

Binary Response (Default)

Returns raw binary data. Best for directly saving files or streaming to users.

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}' \
  --output document.pdf

Headers returned:

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"

Base64 Response

Returns a JSON object with base64-encoded content. Best for embedding in APIs or storing in databases.

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/html?response=base64" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}'

Response:

{
  "data": "JVBERi0xLjcKCjEgMCBvYmoKPDwKL1R5cGUgL0NhdGFsb2cK...",
  "contentType": "application/pdf"
}

Handling Responses

Node.js

Binary Response

const response = await fetch('https://api.pdfgenstudio.com/api/v1/renderer/html', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ html: '<h1>Hello</h1>' }),
});

// Save to file
const buffer = await response.arrayBuffer();
fs.writeFileSync('document.pdf', Buffer.from(buffer));

// Or stream to client (Express)
res.setHeader('Content-Type', 'application/pdf');
res.send(Buffer.from(buffer));

Base64 Response

const response = await fetch('https://api.pdfgenstudio.com/api/v1/renderer/html?response=base64', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ html: '<h1>Hello</h1>' }),
});

const { data, contentType } = await response.json();

// Convert to buffer
const buffer = Buffer.from(data, 'base64');

// Save to file
fs.writeFileSync('document.pdf', buffer);

// Store in database
await db.documents.create({
  content: data,
  mimeType: contentType,
});

Python

Binary Response

import requests

response = requests.post(
    'https://api.pdfgenstudio.com/api/v1/renderer/html',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={'html': '<h1>Hello</h1>'},
)

# Save to file
with open('document.pdf', 'wb') as f:
    f.write(response.content)

Base64 Response

import requests
import base64

response = requests.post(
    'https://api.pdfgenstudio.com/api/v1/renderer/html?response=base64',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={'html': '<h1>Hello</h1>'},
)

result = response.json()

# Decode base64
pdf_content = base64.b64decode(result['data'])

# Save to file
with open('document.pdf', 'wb') as f:
    f.write(pdf_content)

PHP

Binary Response

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.pdfgenstudio.com/api/v1/renderer/html',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['html' => '<h1>Hello</h1>']),
    CURLOPT_RETURNTRANSFER => true,
]);

$pdf = curl_exec($ch);
curl_close($ch);

// Save to file
file_put_contents('document.pdf', $pdf);

// Or output to browser
header('Content-Type: application/pdf');
header('Content-Disposition: inline; filename="document.pdf"');
echo $pdf;

Base64 Response

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.pdfgenstudio.com/api/v1/renderer/html?response=base64',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['html' => '<h1>Hello</h1>']),
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Decode base64
$pdf = base64_decode($response['data']);

// Save to file
file_put_contents('document.pdf', $pdf);

Browser (JavaScript)

Download PDF

async function downloadPDF() {
  const response = await fetch('https://api.pdfgenstudio.com/api/v1/renderer/html', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ html: '<h1>Hello</h1>' }),
  });

  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  
  const a = document.createElement('a');
  a.href = url;
  a.download = 'document.pdf';
  a.click();
  
  window.URL.revokeObjectURL(url);
}

Display in iframe

async function displayPDF() {
  const response = await fetch('https://api.pdfgenstudio.com/api/v1/renderer/html?response=base64', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ html: '<h1>Hello</h1>' }),
  });

  const { data } = await response.json();
  const iframe = document.getElementById('pdf-viewer');
  iframe.src = `data:application/pdf;base64,${data}`;
}

Best Practices

When to Use Binary

• Streaming files directly to users
• Saving files to disk
• Proxying through your backend
• Large files to avoid memory overhead

When to Use Base64

• Storing in databases
• Embedding in JSON APIs
• Sending via WebSocket
• Email attachments
• Data URIs in HTML

Memory Considerations

For large documents, prefer binary responses and streaming:

// Stream to file (Node.js)
const response = await fetch(url, options);
const fileStream = fs.createWriteStream('large-document.pdf');
response.body.pipe(fileStream);

Caching

PDFGen Studio responses can be cached. Use the ETag and Last-Modified headers for efficient caching:

const response = await fetch(url, {
  headers: {
    'If-None-Match': cachedETag,
  },
});

if (response.status === 304) {
  // Use cached version
}