Create Image from Template

Send a POST request to this endpoint to create a new image using a predefined template.

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/template

Request Body

Parameter	Type	Description
templateId	string	The ID of the template to use
modify	object	(Optional) An object containing variables to modify in the template
viewportHeight	number	(Optional) Height of the viewport in pixels (default: 800)
viewportWidth	number	(Optional) Width of the viewport in pixels (default: 1280)
transparentBackground	boolean	(Optional) When set to true, generates the image with a transparent background. Defaults to false if not specified.
strict	boolean	(Optional) When true, answers 422 instead of rendering when there would be `warnings`. See Variables and warnings

cURL


curl --request POST \
  --url https://api.ojo.so/v1/image/template \
  --header 'Authorization: Bearer <your API key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "your-template-id",
    "modify": {
      "title": "Custom Title"
    },
    "viewportHeight": 1000,
    "viewportWidth": 1500
  }'

Python


import requests
 
url = "https://api.ojo.so/v1/image/template"
 
payload = {
"templateId": "your-template-id",
"modify": {
"title": "Custom Title"
},
"viewportHeight": 1000,
"viewportWidth": 1500
}
 
headers = {
"Authorization": "Bearer <your API key>",
"Content-Type": "application/json"
}
 
response = requests.post(url, json=payload, headers=headers)
 
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your API key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: 'your-template-id',
    modify: {
      title: 'Custom Title'
    },
    viewportHeight: 1000,
    viewportWidth: 1500
  })
};
 
fetch('https://api.ojo.so/v1/image/template', 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/template",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 100,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'templateId' => 'your-template-id',
'modify' => [
'title' => 'Custom Title'
],
'viewportHeight' => 1000,
'viewportWidth' => 1500
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <your API key>",
"Content-Type: application/json"
],
]);
 
$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/template"
  payload := strings.NewReader(`{
    "templateId": "your-template-id",
    "modify": {
      "title": "Custom Title"
    },
    "viewportHeight": 1000,
    "viewportWidth": 1500
  }`)
 
  req, _ := http.NewRequest("POST", url, payload)
 
  req.Header.Add("Authorization", "Bearer <your API key>")
  req.Header.Add("Content-Type", "application/json")
 
  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("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"templateId\": \"your-template-id\",\n  \"modify\": {\n    \"title\": \"Custom Title\"\n  },\n  \"viewportHeight\": 1000,\n  \"viewportWidth\": 1500\n}");
Request request = new Request.Builder()
  .url("https://api.ojo.so/v1/image/template")
  .method("POST", body)
  .addHeader("Authorization", "Bearer <your API key>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Variables and warnings

modify merges over the template’s saved variables. Objects merge key by key, so {"issuer": {"signatory": "X"}} keeps the saved issuer.name. An array replaces the saved array whole. A key you leave out prints its saved value, which is usually sample data.

When modify is not empty, the response lists warnings for:

a key the template does not read: 'recipent_name' is not used by the template
an input you left out that printed its saved value: 'recipient_name' was not sent, so the stored sample value was used
an input you left out that has no saved value: 'x' was not sent and has no stored value, so it renders empty
a request field the API does not know, such as a misspelt option: Unknown field `vieportWidth` was ignored. These are listed even when modify is empty

At most 20 are listed, then and N more. Send "strict": true to get these as a 422 instead, before anything is rendered or charged. The paths a template reads are listed as inputs by Get Template.

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."
}

422

Request payload unprocessable, or the render failed. The reason is in logs, such as a missing templateId or one that is not one of your templates. Update the request and try again.


{
  "error": true,
  "message": "Unprocessable Entity",
  "logs": ["Template not found"],
  "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"
}