Quickstart
Render your first PDF with gpdf-api in three minutes — sign up, copy a key, send a request.
Quickstart
You'll have a real PDF on disk in three minutes. The only prerequisite is curl, Node, Go, or Python — pick one.
1. Sign up and get a key
-
Visit app.gpdf.dev/signup. Sign up with email + 6-digit code, or with Continue with Google.
-
Right after signup, the dashboard shows your default API key once. Copy it now into a password manager or a
.envfile:export GPDF_API_KEY=gpdf_a1b2c3d4e5f6g7h8... -
Need another key later? Open /app/keys and click Create key. Free has up to 3 keys; Pro has up to 20.
💡 Tip — Lost your key?
We don't store the raw key anywhere — only an SHA-256 hash. There's no "show key" button. If you lose it, revoke the old one and create a new one. That's by design.
2. Render your first PDF
Pick whichever client you like. Each example renders the same single-page A4 PDF that says "Hello, PDF!".
::code-group
curl https://api.gpdf.dev/v1/pdf \
-H "Authorization: Bearer $GPDF_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": {
"page": { "size": "A4" },
"body": [
{ "text": "Hello, PDF!" }
]
}
}' \
--output hello.pdf
import fs from 'node:fs'
const res = await fetch('https://api.gpdf.dev/v1/pdf', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GPDF_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
template: {
page: { size: 'A4' },
body: [{ text: 'Hello, PDF!' }]
}
})
})
if (!res.ok) {
throw new Error(`${res.status} ${res.statusText}: ${await res.text()}`)
}
fs.writeFileSync('hello.pdf', Buffer.from(await res.arrayBuffer()))
package main
import (
"io"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{
"template": {
"page": {"size": "A4"},
"body": [{"text": "Hello, PDF!"}]
}
}`)
req, _ := http.NewRequest("POST", "https://api.gpdf.dev/v1/pdf", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("GPDF_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
out, _ := os.Create("hello.pdf")
defer out.Close()
io.Copy(out, resp.Body)
}
import os
import requests
res = requests.post(
"https://api.gpdf.dev/v1/pdf",
headers={"Authorization": f"Bearer {os.environ['GPDF_API_KEY']}"},
json={
"template": {
"page": {"size": "A4"},
"body": [{"text": "Hello, PDF!"}],
}
},
)
res.raise_for_status()
open("hello.pdf", "wb").write(res.content)
require 'net/http'
require 'json'
require 'uri'
uri = URI('https://api.gpdf.dev/v1/pdf')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{ENV['GPDF_API_KEY']}"
req['Content-Type'] = 'application/json'
req.body = {
template: {
page: { size: 'A4' },
body: [{ text: 'Hello, PDF!' }]
}
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code} #{res.message}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
File.binwrite('hello.pdf', res.body)
<?php
$payload = json_encode([
'template' => [
'page' => ['size' => 'A4'],
'body' => [['text' => 'Hello, PDF!']],
],
]);
$ch = curl_init('https://api.gpdf.dev/v1/pdf');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('GPDF_API_KEY'),
'Content-Type: application/json',
],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("HTTP $status: $body");
}
file_put_contents('hello.pdf', $body);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
public class Quickstart {
public static void main(String[] args) throws Exception {
String body = """
{
"template": {
"page": {"size": "A4"},
"body": [{"text": "Hello, PDF!"}]
}
}
""";
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://api.gpdf.dev/v1/pdf"))
.header("Authorization", "Bearer " + System.getenv("GPDF_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<Path> res = HttpClient.newHttpClient()
.send(req, HttpResponse.BodyHandlers.ofFile(Path.of("hello.pdf")));
if (res.statusCode() != 200) {
throw new RuntimeException("HTTP " + res.statusCode());
}
}
}
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Quickstart {
static async Task Main() {
var apiKey = Environment.GetEnvironmentVariable("GPDF_API_KEY");
var payload = """
{
"template": {
"page": {"size": "A4"},
"body": [{"text": "Hello, PDF!"}]
}
}
""";
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", apiKey);
using var content = new StringContent(payload, Encoding.UTF8, "application/json");
using var res = await http.PostAsync("https://api.gpdf.dev/v1/pdf", content);
res.EnsureSuccessStatusCode();
await using var fs = File.Create("hello.pdf");
await res.Content.CopyToAsync(fs);
}
}
::
Open hello.pdf in any viewer — that's a real PDF/A-compatible document.
3. Read the response headers
Every successful response includes a few metadata headers worth keeping an eye on:
| Header | Example | What it means |
|---|---|---|
Content-Type |
application/pdf |
Always application/pdf on success. |
Content-Disposition |
attachment; filename="hello.pdf" |
Reflects the options.filename you sent (or the slug, if any). |
X-GPDF-Pages |
1 |
Number of pages in the rendered PDF. |
X-GPDF-Latency-Us |
13872 |
Render time on the server, in microseconds. |
X-GPDF-Quota-Remaining |
499 |
Successful renders left in this billing period. |
X-GPDF-RateLimit-Remaining |
9 |
Tokens left in your per-key bucket. |
X-Request-Id |
req_01HZ… |
Trace ID — quote this when filing a support ticket. |
The full list is in Response headers →.
4. Pass real data into a template
Hard-coding strings is fine for a demo, but in production you usually want one fixed template + per-request data. gpdf-api accepts a Go-template data block alongside the template:
curl https://api.gpdf.dev/v1/pdf \
-H "Authorization: Bearer $GPDF_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"slug": "invoice_q1",
"template": {
"page": { "size": "A4", "margin": "20mm" },
"body": [
{ "text": "Invoice #{{.id}}", "style": { "fontSize": 18, "weight": "bold" } },
{ "spacer": "8mm" },
{ "text": "Billed to: {{.customer.name}}" },
{ "text": "Total: {{.total | printf \"%.2f\"}} USD" }
]
},
"data": {
"id": "INV-001",
"customer": { "name": "Acme, Inc." },
"total": 2720.00
}
}' \
--output invoice.pdf
The same template can be cached on your side and only data (and slug) needs to change.
The slug field is optional but useful — it shows up in the dashboard logs so you can answer "which template was that?" at a glance.
5. Handle errors
Anything other than 200 returns a JSON body shaped like this:
{
"error": {
"code": "rate_limited",
"message": "Too many requests for this key. Retry after 1.0s.",
"request_id": "req_01HZTV...",
"doc_url": "https://docs.gpdf.dev/errors#rate_limited"
}
}
The most common ones to handle:
| HTTP | Code | Fix |
|---|---|---|
| 401 | unauthorized |
Check the Authorization header — typo or revoked key. |
| 402 | quota_exceeded |
Buy an addon pack or upgrade. |
| 413 | payload_too_large |
Trim the input or upgrade for the larger ceiling. |
| 429 | rate_limited |
Honour the Retry-After response header. |
| 503 | service_unavailable |
Retry with exponential backoff (1, 2, 4, 8 s). |
Full catalogue and recommended retry behaviour: Errors →.
6. Check your usage
The dashboard at /app/usage shows your current period as a chart, with daily / hourly breakdowns and remaining quota.
What's next
You now have the basics. The longer reads worth the time:
- Authentication → — key rotation, multiple keys, header reference.
- POST /v1/pdf → — every option on the render endpoint.
- Templates → — tables, columns, page breaks, headers/footers.
- CJK & fonts → — Japanese / Chinese / Korean out of the box, custom font upload.
- Errors → — what to do for every error code.
Something unclear or missing on this page?