Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Choose the API based on what you have: if you are converting a web page or other content into a PDF, PDFShift documents a Ruby Net::HTTP request with a pages parameter. If you already have a PDF and need a new file containing only selected pages, PDF Blocks documents a separate page-extraction endpoint. Their range formats differ, so do not copy one provider’s syntax into the other’s request.
First decide whether you are converting or extracting
“Export selected pages” can mean two different operations:
- Convert, then select: Start with a URL or other content and create a PDF containing only the requested output pages. PDFShift documents this workflow through its conversion endpoint.
- Extract from a PDF: Start with an existing PDF and create another PDF from chosen pages. PDF Blocks documents this workflow through its extraction endpoint.
These are not interchangeable. If your input is already a PDF, a conversion endpoint may not be the right operation; if your input is a web page, an extraction endpoint expects a PDF upload rather than the original page. PDFCrowd also documents a PDF-to-PDF extract operation, but the reviewed reference does not provide a Ruby example.
Convert content and select output pages with PDFShift
PDFShift’s Ruby guide uses the pages field in a JSON request to https://api.pdfshift.io/v3/convert/pdf. It documents a single page such as 2, a range such as 2-4, or a comma-separated list such as 2,4,5,9. The guide does not explicitly establish whether page numbering is zero-based or one-based, so verify the convention in the current PDFShift documentation before relying on page positions.
#1 Best Overall
This version uses Ruby’s standard-library Net::HTTP, reads the API key from an environment variable, checks for a successful HTTP response, and writes the response as binary PDF data. The request shape and selection examples follow PDFShift’s guide; the environment-variable use and explicit error guard are integration hardening.
require 'net/http'
require 'uri'
require 'json'
api_key = ENV.fetch('PDFSHIFT_API_KEY')
params = {
'source' => 'https://example.com/document',
'pages' => '2-4'
}
url = URI('https://api.pdfshift.io/v3/convert/pdf')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = api_key
request.body = params.to_json
response = http.request(request)
raise "PDF conversion failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
File.binwrite('selected-pages.pdf', response.body)Run it safely
- Set
PDFSHIFT_API_KEYin the process environment rather than placing a live key in source code. For example, in a Unix-like shell:export PDFSHIFT_API_KEY='your-key'. - Replace the example
sourcewith the URL or content source expected by your application and setpagesto the provider’s documented syntax. - Run the Ruby script. It writes
selected-pages.pdfonly after receiving a successful HTTP response; a failed response raises an error instead of being silently saved with a PDF filename.
For PDFShift, 2-4 is the documented range form, not the PDF Blocks form. The reviewed guide does not specify what happens when a requested page is outside the generated document or settle indexing; test the required behavior against current provider documentation and a representative input.
Rank #2
Extract selected pages from an existing PDF with PDF Blocks
PDF Blocks documents POST https://api.pdfblocks.com/v1/extract_pages as a multipart form request. Send the input under file and the selected pages under pages. Its Ruby example uses the http gem and authenticates with the X-API-Key header.
Free tools Windows power users keep installed
One-click scans. No signup required.
Unlike the PDFShift guide, PDF Blocks explicitly states that page numbers are 1-based. It documents forms including 1, 1..3,5, 2.., ..-2, and -1. Its extraction treats selections as a set: duplicates and requested ordering are ignored, and output pages remain in document order. Use the provider’s separate reorder operation if you need a different sequence.
Rank #3
require 'http'
response = HTTP
.headers('X-API-Key' => ENV.fetch('PDF_BLOCKS_API_KEY'))
.post('https://api.pdfblocks.com/v1/extract_pages', form: {
file: HTTP::FormData::File.new('input.pdf'),
pages: '1..3,5'
})
raise "PDF extraction failed: #{response.status}" unless response.status.success?
File.binwrite('extracted.pdf', response.body)Install and run
- Install the
httpgem in the application’s dependency environment, for example withgem install httpor by adding it to the project’s Gemfile and running Bundler. - Set
PDF_BLOCKS_API_KEYin the environment, and put the source PDF atinput.pdfor change the file path in the script. - Use the extraction endpoint’s range grammar. The example selects pages 1 through 3 and page 5; the documented syntax is not PDFShift’s
2-4syntax. - Run the script. The code writes
extracted.pdfonly if the response status is successful.
PDF Blocks documents a 200 OK response containing the PDF in the body, 400 when a referenced page does not exist in the input, and 401 when the API key is missing or invalid. Those are useful checks when diagnosing a failed extraction.
Compare the approaches before choosing
| Question | PDFShift conversion | PDF Blocks extraction |
|---|---|---|
| Input and task | Content or a URL converted to a PDF, with output pages selected. | An existing PDF uploaded to produce a PDF of selected pages. |
| Request | JSON POST to https://api.pdfshift.io/v3/convert/pdf. |
Multipart POST to https://api.pdfblocks.com/v1/extract_pages. |
| Ruby dependency shown in vendor material | Ruby standard library Net::HTTP. |
The http gem. |
| Selection syntax | 2, 2-4, or 2,4,5,9; the reviewed guide does not explicitly state indexing. |
Examples include 1, 1..3,5, 2.., ..-2, and -1; numbering is 1-based. |
| Output order | The reviewed guide does not specify ordering behavior. | Pages remain in document order; duplicates and requested order are ignored. |
Both providers’ technical documentation can change. Before adopting either for production, confirm current authentication requirements, page-selection behavior, file-size and usage limits, pricing, data-retention practices, and regional availability directly with the provider. The documentation reviewed here does not establish a complete comparison of those operational terms.
Rank #4
Common errors and fixes
- The saved file is not a usable PDF. Do not write an error response as though it were a PDF. Check the HTTP status before writing bytes; the examples raise an error when the response is not successful. In production, also record a useful status and diagnostic without logging API keys or sensitive document contents.
- PDF Blocks returns 400. Its documentation identifies a reference to a page that does not exist in the source as a cause. Confirm the input PDF’s page count and make sure every selected page is in range.
- PDF Blocks returns 401. The documented causes are a missing or invalid API key. Confirm the environment variable is set in the process that runs Ruby and that the key is current.
- The extracted pages appear in an unexpected order. PDF Blocks preserves source-document order and ignores the requested order and duplicates. Its extraction operation is therefore not a way to reorder pages; use the separate reorder operation when sequence matters.
- The wrong pages are selected during PDFShift conversion. Its guide shows range and list forms but does not explicitly settle indexing. Check the current provider convention and test a small known document before applying selection to a critical output.
- Ruby cannot find
http. The PDF Blocks sample depends on that gem. Install it for the same Ruby environment used to execute the script, or manage it through the application’s Gemfile and Bundler. - The request takes too long or fails intermittently. The reviewed material does not establish timeout, retry, or availability guarantees. Set request timeouts appropriate to your application, handle network and server errors, and retry only where doing so is safe for your workflow; confirm provider-specific guidance before adding automatic retries.
Performance, reliability, and cost considerations
Page selection reduces which pages appear in the output; it does not, from the documentation reviewed here, establish a particular reduction in processing time, transfer size, or price. Measure the behavior with your own document sizes and conversion workload rather than assuming selected pages make a request proportionally faster or cheaper.
For a production integration, keep API keys outside source control, avoid treating every response body as a PDF, and decide how the application should handle timeouts, non-success statuses, and partial workflows. The two code samples are synchronous request patterns; the reviewed documentation does not establish service-level guarantees, retention terms, regional coverage, or plan limits. Check those with the provider before sending sensitive documents or making operational commitments.
Best Value
Or skip the browser setup
If the source is a web page and you would otherwise have to configure a browser to create a PDF or screenshot, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A one-call example is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFor PDF output and page-range settings, use the ScreenshotNeo documentation to select the supported capture options; the example above saves a WebP screenshot and is not an existing-PDF extraction request.
- Before capture, it accepts the cookie or consent banner as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for Claude, Cursor, and other MCP clients. - The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan.
Sign up free for 1,000 screenshots a month with no card.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Frequently Asked Questions
Does selecting pages mean the API will process less data?
Not necessarily. The documentation described here does not quantify processing or transfer savings from selecting pages; verify behavior with your inputs and the provider.
Can I use these examples without sharing documents with a hosted service?
Both examples send requests to hosted API endpoints. If document confidentiality or retention is a concern, review the provider’s current data-handling terms before uploading or converting content.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
