Create Image from HTML

Send a POST request to this endpoint to create a new image using custom HTML.

You will need to authenticate to use this API. See authentication.

This endpoint consumes 1 credit per image. The credit is spent when the render starts, and a render that fails costs nothing: its credit is refunded.

Request


POST https://api.ojo.so/v1/image/html

Headers

Header	Value	Description
Content-Type	text/html	Specify that the request body contains HTML
x-viewport-width	number	(Optional) Width of the viewport in pixels (default: 1280)
x-viewport-height	number	(Optional) Height of the viewport in pixels (default: 800)
x-transparent-background	boolean	(Optional) When set to true, generates the image with a transparent background. Defaults to false if not specified.

Request Body

The request body should contain the HTML content you want to render as an image.

You can also send JSON with Content-Type: application/json. A value in the body wins over its header.

Field	Type	Description
html	string	The HTML to render
viewportWidth	number	(Optional) Width of the viewport in pixels (default: 1280)
viewportHeight	number	(Optional) Height of the viewport in pixels (default: 800)
transparentBackground	boolean	(Optional) When true, renders without a background colour

cURL


curl --request POST \
  --url https://api.ojo.so/v1/image/html \
  --header 'Authorization: Bearer <your API key>' \
  --header 'Content-Type: text/html' \
  --header 'x-viewport-width: 1500' \
  --header 'x-viewport-height: 1000' \
  --data '<html><body><div id="main-content"><h1>Hello, World!</h1></div></body></html>'

Python


import requests
 
url = "https://api.ojo.so/v1/image/html"
 
payload = "<html><body><div id=\"main-content\"><h1>Hello, World!</h1></div></body></html>"
 
headers = {
"Authorization": "Bearer <your API key>",
"Content-Type": "text/html",
"x-viewport-width": "1500",
"x-viewport-height": "1000"
}
 
response = requests.post(url, data=payload, headers=headers)
 
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your API key>',
    'Content-Type': 'text/html',
    'x-viewport-width': '1500',
    'x-viewport-height': '1000'
  },
  body: '<html><body><div id="main-content"><h1>Hello, World!</h1></div></body></html>'
};
 
fetch('https://api.ojo.so/v1/image/html', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

PHP


<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ojo.so/v1/image/html",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 100,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "<html><body><div id=\"main-content\"><h1>Hello, World!</h1></div></body></html>",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <your API key>",
"Content-Type: text/html",
"x-viewport-width: 1500",
"x-viewport-height: 1000"
],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

Go


package main
 
import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)
 
func main() {
  url := "https://api.ojo.so/v1/image/html"
  payload := strings.NewReader(`<html><body><div id="main-content"><h1>Hello, World!</h1></div></body></html>`)
 
  req, _ := http.NewRequest("POST", url, payload)
 
  req.Header.Add("Authorization", "Bearer <your API key>")
  req.Header.Add("Content-Type", "text/html")
  req.Header.Add("x-viewport-width", "1500")
  req.Header.Add("x-viewport-height", "1000")
 
  res, _ := http.DefaultClient.Do(req)
 
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)
 
  fmt.Println(string(body))
}

Java


OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("text/html");
RequestBody body = RequestBody.create(mediaType, "<html><body><div id=\"main-content\"><h1>Hello, World!</h1></div></body></html>");
Request request = new Request.Builder()
  .url("https://api.ojo.so/v1/image/html")
  .method("POST", body)
  .addHeader("Authorization", "Bearer <your API key>")
  .addHeader("Content-Type", "text/html")
  .addHeader("x-viewport-width", "1500")
  .addHeader("x-viewport-height", "1000")
  .build();
Response response = client.newCall(request).execute();

Response

200

Everything went as planned and your image is generated.


{
  "id": "image-id",
  "imageUrl": "https://example.com/path/to/image.png",
  "createdAt": "2023-08-29T12:34:56Z"
}

401

Your API key might be invalid or expired.


{
  "error": true,
  "message": "Unauthorized",
  "status": 401,
  "title": "Unauthorized",
  "detail": "Unauthorized"
}

402

Your credits do not cover this render, so it is refused before it renders and nothing is spent.


{
  "error": true,
  "message": "Not enough credits for this render. Choose a plan at https://ojo.so/pricing.",
  "status": 402,
  "title": "Payment Required",
  "detail": "Not enough credits for this render. Choose a plan at https://ojo.so/pricing."
}

415

The body was sent with another Content-Type than text/html or application/json.


{
  "error": true,
  "message": "Unsupported Media Type",
  "logs": ["Send the HTML with Content-Type: text/html, or {\"html\": \"...\"} with Content-Type: application/json"],
  "status": 415,
  "title": "Unsupported Media Type",
  "detail": "Unsupported Media Type"
}

422

Request payload unprocessable, or the render failed. The reason is in logs. Update the request and try again.


{
  "error": true,
  "message": "Unprocessable Entity",
  "logs": ["Template missing. Send html in the request body"],
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "Unprocessable Entity"
}

429

You have hit your rate limit. You can view rate limit details here.


{
  "error": true,
  "message": "Render rate limit reached: 60 image and PDF renders per minute",
  "logs": ["Try again in 2 minutes."],
  "code": "rate_limited.render",
  "retryAfter": 120,
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Render rate limit reached: 60 image and PDF renders per minute"
}

500

An unexpected error occurred. Try again later. If the issue persists, please reach out.


{
  "error": true,
  "message": "Internal Server Error",
  "status": 500,
  "title": "Internal Server Error",
  "detail": "Internal Server Error"
}