PRNT REST API
文档与 SDK

数分钟内即可将程序化网页截图集成到您的应用中。RESTful 设计、JSON 响应以及 HMAC 签名 Webhook。

REST API v1.0

低于 42ms 极速响应

OpenAPI 3.0 规范

提供 5 种官方 SDK

低于 50ms 渲染

分布在全球 12 个边缘节点的预热 Chromium 实例，重复请求可享即时 CDN 缓存命中。

像素级精准 DOM

完整 JS 水合、WebGL 帧、无限滚动、Retina 缩放倍率以及自动关闭 Cookie 弹窗。

加固级安全保障

自动 SSRF 防护、单次运行隔离 Docker 沙箱、目标 Cookie 零持久化以及 256 位 TLS 1.3 加密。

多语言 SDK 支持

原生 SDK 库与开箱即用的 cURL、Python、Node.js、PHP 及 Go 示例，支持类型化参数。

01 快速入门指南

使用我们的 RESTful API，在 60 秒内发起您的第一次程序化网页截图请求：

注册免费开发者账号以获取您的 API 密钥。
前往 API 密钥控制面板复制您的 Bearer Token。
向 /v1/capture 端点发送包含目标 URL 的 HTTP POST 请求。

# Request full-page PNG screenshot
curl -X POST "https://api.prnt.tr/v1/capture" \
  -H "Authorization: Bearer prnt_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com",
    "format": "png",
    "full_page": true,
    "viewport": { "width": 1920, "height": 1080 }
  }' --output screenshot.png

import requests

url = "https://api.prnt.tr/v1/capture"
headers = {
    "Authorization": "Bearer prnt_live_your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "url": "https://github.com",
    "format": "png",
    "full_page": True
}

response = requests.post(url, json=payload, headers=headers)
with open("screenshot.png", "wb") as f:
    f.write(response.content)
print("Screenshot saved successfully!")

import fs from 'fs/promises';

const response = await fetch('https://api.prnt.tr/v1/capture', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer prnt_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://github.com',
    format: 'png',
    full_page: true
  })
});

const buffer = Buffer.from(await response.arrayBuffer());
await fs.writeFile('screenshot.png', buffer);
console.log('Screenshot captured successfully.');

<?php
$apiKey = 'prnt_live_your_api_key_here';
$ch = curl_init('https://api.prnt.tr/v1/capture');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://github.com',
        'format' => 'png',
        'full_page' => true
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$image = curl_exec($ch);
file_put_contents('screenshot.png', $image);
curl_close($ch);

02 身份验证与安全

PRNT 通过加密 Bearer Token 验证 API 请求。请在每个请求的 Authorization 请求头中包含密钥：

安全最佳实践： 切勿在公开的客户端 JavaScript、GitHub 仓库或前端打包文件中暴露 API 密钥。请始终通过后端服务发起请求。

03 基础 URL 与内容格式

所有 API 接口均通过 TLS 1.3 安全提供服务。生产环境入口地址为：

PRNT 支持多种针对网络、打印和归档量身定制的图像输出编码：

格式	MIME 类型	最佳适用场景
`png`	`image/png`	默认格式。无损画质，非常适合清晰文本、UI 界面元素及透明背景。
`jpeg` / `jpg`	`image/jpeg`	专为图片密集型网页优化文件大小，支持 `quality` 质量调节（1-100）。
`webp`	`image/webp`	现代高压缩比网页格式，文件体积比 JPEG 小达 30%。
`pdf`	`application/pdf`	支持分页矢量文档导出，适用于发票、法律合规及归档打印。

04 POST /v1/capture

将网页渲染为高分辨率图像或文档的核心程序化端点。

请求参数（JSON 请求体）

参数名称	数据类型	状态	说明与默认值
`url`	string	必填	完整的目标网页 URL（必须包含 `https://` 或 `http://`）。
`format`	string	可选	`png` (默认), `jpeg`, `webp`, 或 `pdf`.
`full_page`	boolean	可选	自动向下滚动触发懒加载 DOM 元素以截取完整页面高度。默认为 `false`。
`viewport.width`	integer	可选	浏览器视口宽度（像素）。默认为 `1920`。
`viewport.height`	integer	可选	浏览器视口高度（像素）。默认为 `1080`。
`delay`	integer	可选	DOM 加载完成后到截图前的等待时间（毫秒，0 – 10000ms）。默认为 `0`。
`dark_mode`	boolean	可选	模拟 `prefers-color-scheme: dark` CSS 媒体查询。默认为 `false`。
`block_cookie_banners`	boolean	可选	自动检测并清理弹出的 GDPR/Cookie 授权弹窗。默认为 `true`。
`custom_css`	string	可选	截图前注入自定义 CSS 规则（如 `.announcement { display: none; }`）。
`custom_js`	string	可选	截图前在页面中执行自定义客户端 JavaScript 代码。

05 HTTP 状态码与错误处理

PRNT 返回标准 HTTP 响应状态码，并附带结构化的 JSON 错误信息：

HTTP 状态码	错误常量	原因与解决方案
`200 OK`	SUCCESS	截图成功渲染并作为二进制图像或 CDN 资源返回。
`400 Bad Request`	INVALID_PARAMETER	缺少目标 URL、尺寸参数无效或 JSON 格式错误。
`401 Unauthorized`	INVALID_API_KEY	请求头中缺少或使用了已撤销的 API Bearer Token。
`403 Forbidden`	DOMAIN_BLOCKED	请求的目标域名违反了我们的使用规范或被 SSRF 防火墙拦截。
`429 Too Many Requests`	RATE_LIMIT_EXCEEDED	已达到您套餐的请求配额或并发上限。请升级套餐以提升限额。
`504 Gateway Timeout`	RENDER_TIMEOUT	目标网页未能在 30 秒执行窗口内响应或完成渲染。

06 SDK 代码示例与集成库

查看官方 SDK 和 HTTP 客户端的即用型示例代码：

package main

import (
	"bytes"
	"encoding/json"
	"io"
	"net/http"
	"os"
)

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"url":       "https://github.com",
		"format":    "png",
		"full_page": true,
	})

	req, _ := http.NewRequest("POST", "https://api.prnt.tr/v1/capture", bytes.NewBuffer(payload))
	req.Header.Set("Authorization", "Bearer prnt_live_your_api_key_here")
	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("screenshot.png")
	defer out.Close()
	io.Copy(out, resp.Body)
}

# pip install prnt-sdk
from prnt import PrntClient

client = PrntClient(api_key="prnt_live_your_api_key_here")

screenshot = client.capture(
    url="https://github.com",
    format="png",
    full_page=True,
    dark_mode=True,
    delay=500
)

screenshot.save("github_dark.png")

// npm install @prnt/sdk
import { PrntClient } from '@prnt/sdk';

const prnt = new PrntClient({ apiKey: 'prnt_live_your_api_key_here' });

const image = await prnt.capture({
  url: 'https://github.com',
  format: 'webp',
  fullPage: true,
  blockCookieBanners: true
});

await image.save('output.webp');

PRNT REST API 文档与 SDK