# HTML to Image API (html2img.com): Full Reference
> REST API that converts HTML, CSS, or any URL into a PNG image. Authenticate with one header, POST JSON, receive a CDN-hosted PNG URL. 50 free renders at signup (no credit card). Paid plans from $9/month for 1,000 renders up to $300/month for 100,000. Paid renders are hosted permanently; free-tier renders are hosted for 7 days, and upgrading to any paid plan makes existing renders permanent.
This file bundles the full documentation for LLMs and other automated readers. The shorter index is at [/llms.txt](https://html2img.com/llms.txt). The site sitemap is at [/sitemap.xml](https://html2img.com/sitemap.xml).
---
## What you can do with html2img.com
- **Open Graph and social share images** generated on demand (Twitter, LinkedIn, Facebook, Instagram, Pinterest, YouTube thumbnails).
- **Invoices, receipts, tickets and certificates** as PNG attachments for transactional email.
- **Screenshots of any public URL**, full-page or cropped to a CSS selector, with cookie banners stripped via injected CSS.
- **Code screenshots, GitHub repo cards, GitHub social previews** for launches, release notes and changelogs.
- **Charts, dashboards and embed cards** exported to PNG with full JavaScript support up to a 30-second budget.
- **Real estate listings, product cards, weather widgets, QR codes** and other parameterized image shapes via named templates.
Anywhere your stack already speaks HTTP, you can render an image: PHP, Laravel, Rails, Python, Node.js, Express, Next.js, Remix, Vue, Nuxt, FastAPI, Flask, Django.
## Pricing
Free: 50 credits at signup (one-time allowance, no monthly reset), no credit card. Every feature available except the MCP server, which is on paid plans only. Free renders are hosted for 7 days; paid renders are hosted permanently.
- $9/month: 1,000 credits
- $25/month: 3,000 credits
- $60/month: 10,000 credits
- $120/month: 30,000 credits
- $225/month: 65,000 credits
- $300/month: 100,000 credits
One credit = one render, image or PDF. Running out returns HTTP 402 `insufficient_credits`, carrying the renewal date on a paid plan or the upgrade URL on the free tier, so there is no surprise billing and no automatic overage charge. There is no rate-limit response. No per-seat pricing. Cancel from the dashboard at any time. Yearly invoicing available with a small discount. Non-profit and open-source discounts considered case by case.
[Pricing page](https://html2img.com/pricing) · [Compare to alternatives](https://html2img.com/compare)
## Frequently asked
**Free tier?** 50 renders at signup, no credit card required, all available immediately. Every feature on paid plans is available on the free plan, including templates, webhooks and DPI control, except the MCP server (paid plans only). Free renders are hosted for 7 days; upgrading makes everything already rendered permanent.
**Which languages?** Any language that can make an HTTP request. Worked examples published for PHP, Laravel, Ruby on Rails, Python, JavaScript, Node.js, React and Vue.
**HTML vs Screenshot endpoint?** HTML accepts raw markup and runs your inline JavaScript. Screenshot accepts a URL and captures the rendered page without running user-supplied JavaScript. Pick HTML for full control, Screenshot for capturing existing pages.
**Rendering accuracy?** Real Chrome: flexbox, grid, custom properties, custom fonts and JavaScript all behave as they do in the browser.
**What's a template?** A named, parameterized image design hosted on our side. POST a JSON payload to its endpoint, receive a styled PNG, skip the HTML step.
**Limits?** 30-second budget on sync requests. For longer renders use `webhook_url`. Viewport up to 5000x5000. DPI 1–4 (forced to 1 when `fullpage` is true).
---
## The three endpoints
Base URL: `https://app.html2img.com`
### 1. HTML and CSS API: `POST /api/html`
Send raw HTML and CSS. We render it in Chrome and return a PNG URL. Inline `",
"wait_for_selector": "#chart canvas"
}
```
### Screenshot endpoint
Cannot run user-supplied JavaScript. The target page runs its own scripts; we capture the result. Use `wait_for_selector` for elements that load late, or `ms_delay` for iframes/embeds where the selector isn't visible from the outer document.
---
## Testing and debugging
### Reproducing renders locally
1. Save HTML to a file and open in Chrome.
2. DevTools → device toolbar → set width/height to match what you'll send.
3. Verify fonts load. If Inter falls back to Times locally, it'll fall back the same way in the API.
4. Use Chrome's "Capture screenshot" in DevTools to compare against what the API produces.
### Why a render differs from your browser
1. **Missing fonts**: use Google Fonts via `` or self-host with a public `@font-face` URL.
2. **JS timing**: pair `wait_for_selector` or `ms_delay` with the marker your code sets after data is ready.
3. **User-agent-dependent CSS**: hover, focus, prefers-color-scheme behave differently in headless. Inject `prefers-color-scheme: dark` overrides via `css` if needed.
4. **Slow third-party assets**: strip them with `css { display: none !important }` for ad slots and analytics overlays.
### Webhook testing in development
- [webhook.site](https://webhook.site) for a free temporary URL.
- ngrok (`ngrok http 3000`) to expose your local server with a stable HTTPS URL.
---
## Language guides
Every example assumes the API key lives in `HTML2IMG_API_KEY` (or your platform's equivalent env var). All examples return the same JSON shape (`success`, `credits_remaining`, `id`, `url`).
The snippets below are raw HTTP. Most stacks also have an official package, each documented in full at https://html2img.com/integrations : PHP (`html2img/html2img-php`), Laravel (`html2img/html2img-laravel`), JavaScript (`@html2img/client`), Python (`html2img-client`), Django (`html2img-django`), Ruby and Rails (`html2img-client`), plus plugins for WordPress, Statamic and Craft CMS and an Action for GitHub workflows.
### PHP (cURL)
```php
true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: ' . getenv('HTML2IMG_API_KEY'),
],
CURLOPT_POSTFIELDS => json_encode(array_merge(['html' => $html], $options)),
]);
$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($statusCode !== 200 || empty($result['success'])) {
throw new Exception($result['message'] ?? 'Render failed');
}
return $result;
}
$result = htmlToImage('
Hello
', ['width' => 1200, 'height' => 630]);
echo $result['url'];
```
### PHP (Guzzle service class)
```php
namespace App\Services;
use GuzzleHttp\Client;
class Html2ImgClient
{
private Client $client;
public function __construct(string $apiKey)
{
$this->client = new Client([
'base_uri' => 'https://app.html2img.com/api/',
'headers' => ['X-API-Key' => $apiKey, 'Content-Type' => 'application/json'],
]);
}
public function renderHtml(string $html, array $options = []): string
{
$response = $this->client->post('html', ['json' => array_merge(['html' => $html], $options)]);
return json_decode($response->getBody()->getContents(), true)['url'];
}
public function screenshot(string $url, array $options = []): string
{
$response = $this->client->post('screenshot', ['json' => array_merge(['url' => $url], $options)]);
return json_decode($response->getBody()->getContents(), true)['url'];
}
}
```
### Laravel (Http facade)
```php
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
->post('https://app.html2img.com/api/html', [
'html' => view('emails.invoice', ['order' => $order])->render(),
'width' => 800,
'height' => 600,
]);
$url = $response->json('url');
```
### Laravel (queueable job)
```php
namespace App\Jobs;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Http;
use App\Models\Invoice;
class RenderInvoiceImage implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(public Invoice $invoice) {}
public function handle(): void
{
$response = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
->post('https://app.html2img.com/api/v1/templates/invoice-image', [
'invoice_number' => $this->invoice->number,
'business_name' => $this->invoice->business->name,
'client_name' => $this->invoice->client->name,
'items' => $this->invoice->items->map->toApiArray()->all(),
'total' => $this->invoice->total_formatted,
]);
$this->invoice->update(['image_url' => $response->json('url')]);
}
}
RenderInvoiceImage::dispatch($invoice);
```
### Ruby on Rails (Net::HTTP)
```ruby
require 'net/http'
require 'json'
uri = URI('https://app.html2img.com/api/html')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = Rails.application.credentials.html2img[:api_key]
request.body = {
html: render_to_string(template: 'invoices/template', layout: false, locals: { order: order }),
width: 800,
height: 600
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
url = JSON.parse(response.body)['url']
```
### Ruby on Rails (Faraday with retries)
```ruby
require 'faraday'
require 'faraday/retry'
class Html2ImgClient
def initialize(api_key)
@conn = Faraday.new(url: 'https://app.html2img.com/api/') do |f|
f.request :retry, max: 3, interval: 0.5, backoff_factor: 2,
exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError]
f.request :json
f.response :json
f.headers['X-API-Key'] = api_key
f.adapter Faraday.default_adapter
end
end
def render_html(html, options = {})
@conn.post('html', { html: html }.merge(options)).body['url']
end
def render_template(slug, payload)
@conn.post("v1/templates/#{slug}", payload).body['url']
end
end
```
ActiveStorage attach pattern:
```ruby
require 'open-uri'
URI.open(api_url) do |image|
order.invoice_image.attach(io: image, filename: "invoice-#{order.id}.png", content_type: 'image/png')
end
```
### Python (requests)
```python
import os, requests
response = requests.post(
'https://app.html2img.com/api/html',
json={'html': '