> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pdfshift.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Convert to PNG
This endpoint will convert an HTML document to a PNG image.
You can specify additional options to customize the output image, such as capturing the full page, selecting specific elements using CSS selectors, or defining a clip region.
Only one of `fullpage`, `css_selector`, or `clip` can be set at a time.
Please note that the response from this endpoint will vary depending on some parameters.
You can read more at [Varying responses](/docs/varying-responses).
## OpenAPI
````yaml https://api.pdfshift.io/openapi.json post /convert/png
openapi: 3.0.3
info:
title: PDFShift API Documentation
version: '3.0'
description: >-
This is the documentation for the PDFShift API.
Our aim here is to provide you with a clear, concise and complete set of
tool to generate the PDF you want.
Don't forget to add the `sandbox` parameter to `True` while testing the API,
this won't use your credits and generate free PDF (with a watermark).
But if you forgot to set it, don't worry ; Send us a message and we'll reset
your credits usage.
termsOfService: https://pdfshift.io/terms
contact:
name: PDFShift
url: https://pdfshift.io
email: support@pdfshift.io
x-logo:
url: https://pdfshift.io/images/favicons/android-chrome-512x512.png
servers:
- url: https://api.pdfshift.io/v3
description: ''
x-last-modified: 1764750693905
security:
- apiKeyHeader: []
externalDocs:
description: You can access our documentation online by visiting https://docs.pdfshift.io
url: https://docs.pdfshift.io
paths:
/convert/png:
post:
tags: []
summary: Convert to PNG
parameters:
- name: X-Processor-Version
in: header
description: >-
Specifies the Chromium version that will be used for the conversion.
Right now, only "116" and "142" are accepted.
All new users are automatically using the latest version.
required: false
schema:
type: string
enum:
- '116'
- '142'
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ImageConvertForm'
- $ref: '#/components/schemas/ConvertForm'
required:
- source
responses:
'200':
description: PNG file generated successfully
headers:
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
X-RateLimit-Limit:
description: >-
The maximum number of requests allowed in the current rate limit
window.
schema:
type: integer
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets (Unix
timestamp).
schema:
type: integer
format: int64
X-Response-Status-Code:
description: >-
Provides the status code PDFShift got when loading your source
when it is an HTTP request.
schema:
type: integer
X-PDFShift-Processor:
description: >-
Returns the name of the PDFShift’s server that ran the
conversion.
schema:
type: string
X-Credits-Cost:
description: Indicates the number of credits that this generation requires.
schema:
type: integer
X-Credits-Used:
description: >-
Contrary to X-Credits-Cost, this header indicates the number of
credits that were decreased from your account. It is identical
to X-Credits-Cost excepted if you passed the sandbox parameter,
in which case the value will be at 0.
schema:
type: integer
X-Response-Duration:
description: >-
The number of miliseconds it took to load the HTML source
provided in the request.
schema:
type: integer
X-PDFShift-Duration:
description: >-
The number of miliseconds it took to load the source and then
generate the PDF document. This value should be closer to the
Time To First Byte duration you can have on your end.
schema:
type: integer
content:
image/png:
schema:
type: string
format: binary
example: <...PNG binary data...>
application/json:
schema:
type: object
properties:
success:
type: boolean
url:
type: string
format: uri
filesize:
type: integer
duration:
type: integer
response:
type: object
executed:
type: string
format: date-time
required:
- success
- url
- filesize
- duration
- response
- executed
example:
success: true
url: >-
https://s3.amazonaws.com/pdfshift/d/2/2019-05/99c456250a01448686d81752a3fb5beb/15466098-8368-49e1-ac33-ff4c3941a0df.pdf
filesize: 259972
duration: 1500
response:
duration: 2562
status-code: 200
executed: '2025-12-02T12:34:56.789Z'
'202':
description: >-
Conversion request accepted and queued for processing. Returned when
the `webhook` parameter is used.
headers:
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
X-RateLimit-Limit:
description: >-
The maximum number of requests allowed in the current rate limit
window.
schema:
type: integer
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets (Unix
timestamp).
schema:
type: integer
format: int64
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
queued:
type: boolean
example:
success: true
queued: true
'400':
description: >-
Bad request. Data passed to the request were invalid or wrongly
formatted.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized. Invalid auth key, missing, or disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden. No remaining credits left.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'408':
description: Request Timeout. The requested page took too long to load.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests. You have been rate limited.
headers:
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
X-RateLimit-Limit:
description: >-
The maximum number of requests allowed in the current rate limit
window.
schema:
type: integer
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets (Unix
timestamp).
schema:
type: integer
format: int64
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
ImageConvertForm:
type: object
properties:
viewport:
type: string
default: 1280x1024
description: >-
Default size of the rendering window. This will define the size of
your image when using fullpage. Format in {width}x{height} (in
pixels).
transparent:
type: boolean
default: false
description: |-
If set to true, the image will have a transparent background.
**Note**: This option is only available when outputting PNG images.
fullpage:
type: boolean
default: false
description: |-
Capture the full scrollable page.
Only one of `fullpage`, `css_selector`, or `clip` can be set.
css_selector:
type: string
default: null
description: |-
CSS selector for the element to capture.
Only one of `fullpage`, `css_selector`, or `clip` can be set.
clip:
type: object
description: |-
Clip region to capture.
Only one of `fullpage`, `css_selector`, or `clip` can be set.
properties:
width:
type: integer
minimum: 1
description: Width of the region to capture (in pixels).
height:
type: integer
minimum: 1
description: Height of the region to capture (in pixels).
x:
type: integer
description: X coordinate of the top-left corner (in pixels).
'y':
type: integer
description: Y coordinate of the top-left corner (in pixels).
required:
- width
- height
- x
- 'y'
quality:
type: integer
minimum: 10
maximum: 100
default: 80
description: Quality of the output image (only for JPEG, 10-100).
dpi:
type: integer
enum:
- 1
- 2
- 4
default: 1
description: DPI scaling factor. Must be one of 1, 2, or 4.
ConvertForm:
type: object
properties:
source:
oneOf:
- type: string
- type: array
items:
type: string
description: >-
Original document to convert to PDF. PDFShift will automatically
detect if it's an URL and load it, or an HTML document and charge
it.
You can also send an array of documents to convert if parallel
conversions is enabled on your account. In that case, you will also
need to provide the webhook parameters as this operation is
asynchronous.
sandbox:
type: boolean
default: false
description: >-
Will generates documents that doesn't count in the credits. The
generated document will come with a watermark and you are limited to
10 documents per minutes.
encode:
type: boolean
default: false
description: >-
Will return the generated PDF in Base64 encoded format, instead of
raw.
filename:
type: string
description: >-
Name of the destination file.
Only an alphanumerical value with "-" or "_", of at least 7 chars
accepted.
If given, the response **will not be the PDF**, but a JSON response
containing an url parameter to an Amazon S3 bucket, to download the
file.
The file will be **kept for 2 days**, then automatically deleted.
See [Saving the document to Amazon S3](/docs/saving-to-s3) for an
example.
s3_destination:
type: string
description: >-
Path to your S3 bucket, in order to save the converted PDF directly
into your AWS S3 account.
Use a full path value like
`s3://doc-example-bucket/pdfshift/upload/86aa3ede7d05.pdf`.
See [Saving to your Amazon S3](/docs/saving/to-s3) for more details.
Note that you can also save to [Google Cloud
Storage](/docs/saving/to-gs) and reach out to us if you want to
store to other services as well
use_print:
type: boolean
default: false
description: Use the print stylesheet instead of the general one.
css:
type: string
description: >-
Will append this CSS styles to the document before saving it. Can be
an URL or a String of CSS rules.
javascript:
type: string
description: >-
Will execute the given Javascript before saving the document. Can be
an URL or a String of JS code.
delay:
type: integer
default: 0
minimum: 0
maximum: 10000
description: >-
In milliseconds. Will wait for this duration before capturing the
document. Up to 10 seconds max.
timeout:
type: integer
minimum: 0
maximum: 900
description: >-
If provided, will kill the page loading at a specified time without
stopping with a TimeoutError. Value in seconds.
wait_for:
type: string
description: >-
Name of a function available globally.
When present, PDFShift will wait for this function to return a
truthy value (true, 1, a string, etc) or up to 30 seconds, then
proceed to the conversion.
If the function never returns a truthy value in the allocated time,
the conversion will fail with an error.
wait_for_network:
type: boolean
default: true
description: >-
If set to true, will wait that there was no network requests in the
last 500ms.
ignore_long_polling:
type: boolean
default: false
description: >-
Will not wait for long-polling request to end before generating the
document.
This can be helpful when loading a page that have websockets or long
running queries that have no impact on the generated document.
Requires `wait_for_network` to be set to true, otherwise the
conversion never waits for network requests at all.
disable_javascript:
type: boolean
default: false
description: Will not execute the javascript at all in the document.
lazy_load_images:
type: boolean
default: false
description: >-
When set to true, will scroll the page to the bottom to trigger
loading the images with lazy loading before saving the document.
raise_for_status:
type: boolean
default: false
description: >-
Won't convert the document if the loaded source (when HTTP) returns
a non 2XX response.
webhook:
oneOf:
- $ref: '#/components/schemas/WebhookForm'
- type: string
format: uri
description: >-
An URL where we will send a POST request containing a JSON body
similar to when you use the filename parameter.
The JSON response will contain a URL key that points to your file,
stored on Amazon S3.
**Note**: When the conversion fail, we also do a `POST` request to
your endpoint, but with an `error` key instead.
We recommend you to first check if the body contains the `error`
before processing the document, and act accordingly.
auth:
$ref: '#/components/schemas/BasicAuthForm'
description: >-
Basic authentication that will be sent along the request to load the
source when it's an URL.
http_headers:
type: object
additionalProperties:
type: string
description: >-
List of HTTP headers that you can pass to the request when loading
the source URL.
cookies:
type: array
items:
$ref: '#/components/schemas/CookieForm'
description: >-
List of cookies you want to send along with the requests when
loading the source.
They must be provided as an array of objects.
is_hipaa:
type: boolean
default: false
description: >-
When set to True, ensure the conversion's parameters are compliant
to HIPAA regulations.
This will disable features such as `filename` or `webhook` when the
`s3_destination` is managed by PDFShift, to avoid storing any
sensitive documents on PDFShift's servers. See [Handling sensitive
documents](https://help.pdfshift.io/how-do-you-handle-sensitive-documents)
for more details.
is_gdpr:
type: boolean
default: false
description: >-
When set to True, ensure the conversion's parameters are compliant
to GDPR regulations.
This will disable features such as `filename` or `webhook` when the
`s3_destination` is managed by PDFShift, to avoid storing any
sensitive documents on PDFShift's servers. See [Handling sensitive
documents](https://help.pdfshift.io/how-do-you-handle-sensitive-documents)
for more details.
log_request:
type: boolean
default: false
description: >-
Log the request parameters. Useful for debugging purposes with
PDFShift support.
required:
- source
Errors:
type: object
properties:
success:
type: boolean
errors:
type: object
code:
type: integer
format: int32
Error:
type: object
properties:
success:
type: boolean
error:
type: string
code:
type: integer
format: int32
WebhookForm:
type: object
properties:
url:
type: string
format: uri
method:
type: string
default: POST
auth:
$ref: '#/components/schemas/BasicAuthForm'
headers:
type: object
additionalProperties:
type: string
required:
- url
BasicAuthForm:
type: object
properties:
username:
type: string
default: null
password:
type: string
default: null
CookieForm:
type: object
properties:
name:
type: string
value:
type: string
secure:
type: boolean
default: false
http_only:
type: boolean
default: false
required:
- name
- value
securitySchemes:
apiKeyHeader:
type: apiKey
description: >-
Authenticate your account by including your secret key in API requests.
You can manage your API keys in the
[Dashboard](https://app.pdfshift.io/dashboard/).
Authentication to the API is performed by using the HTTP Header
X-API-Key.
name: X-API-Key
in: header
x-last-modified: 1764750344730
````