Create Images from Templates (Bulk)

Send a POST request to this endpoint to create multiple images at once using multiple templates.

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

This endpoint consumes 1 credit per image generated in the batch. For example, requesting 10 image variations will consume 10 credits. They are spent when the batch starts, and an image that fails costs nothing: its credit is refunded.

Request


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

Request Body

Parameter	Type	Description
templates	array	Array of template objects to generate images from
defaultOptions	object	(Optional) Default options to apply to all templates unless overridden
strict	boolean	(Optional) When true, answers 422 with every image’s `warnings` before any image is rendered or charged

A field the API does not know, at the top level, in defaultOptions or in a template object, is ignored and listed in the response’s top-level warnings, such as templates[0]: unknown field `modifcations` was ignored. With strict, it answers 422 instead.

Template Object

Parameter	Type	Description
templateId	string	The ID of the template to use
modifications	array	Array of objects containing variables to modify in the template for each image
modify	object or array	Instead of `modifications`: the variables for one image, or an array as `modifications`. Send one of the two
viewportHeight	number	(Optional) Height of the viewport in pixels (overrides defaultOptions)
viewportWidth	number	(Optional) Width of the viewport in pixels (overrides defaultOptions)
transparentBackground	boolean	(Optional) When true, generates images with transparent backgrounds (overrides defaultOptions)

DefaultOptions Object

Parameter	Type	Description
viewportHeight	number	(Optional) Default height of the viewport in pixels (default: 800)
viewportWidth	number	(Optional) Default width of the viewport in pixels (default: 1280)
transparentBackground	boolean	(Optional) Default transparent background setting (default: false)

cURL


curl --request POST \
  --url https://api.ojo.so/v1/image/bulk \
  --header 'Authorization: Bearer <your API key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "defaultOptions": {
      "viewportWidth": 1200,
      "viewportHeight": 630,
      "transparentBackground": false
    },
    "templates": [
      {
        "templateId": "product-card-template",
        "modifications": [
          {
            "title": "Premium Headphones",
            "price": "$199.99",
            "color": "#FF5733"
          },
          {
            "title": "Wireless Earbuds",
            "price": "$89.99",
            "color": "#33FF57"
          }
        ]
      },
      {
        "templateId": "social-post-template",
        "viewportHeight": 1080,
        "viewportWidth": 1080,
        "modifications": [
          {
            "heading": "Summer Sale",
            "tagline": "Up to 50% off",
            "bgColor": "#3357FF"
          }
        ]
      }
    ]
  }'

Python


import requests
 
url = "https://api.ojo.so/v1/image/bulk"
 
payload = {
"defaultOptions": {
"viewportWidth": 1200,
"viewportHeight": 630,
"transparentBackground": False
},
"templates": [
{
"templateId": "product-card-template",
"modifications": [
{
"title": "Premium Headphones",
"price": "$199.99",
"color": "#FF5733"
},
{
"title": "Wireless Earbuds",
"price": "$89.99",
"color": "#33FF57"
}
]
},
{
"templateId": "social-post-template",
"viewportHeight": 1080,
"viewportWidth": 1080,
"modifications": [
{
"heading": "Summer Sale",
"tagline": "Up to 50% off",
"bgColor": "#3357FF"
}
]
}
]
}
 
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({
    "defaultOptions": {
      "viewportWidth": 1200,
      "viewportHeight": 630,
      "transparentBackground": false
    },
    "templates": [
      {
        "templateId": "product-card-template",
        "modifications": [
          {
            "title": "Premium Headphones",
            "price": "$199.99",
            "color": "#FF5733"
          },
          {
            "title": "Wireless Earbuds",
            "price": "$89.99",
            "color": "#33FF57"
          }
        ]
      },
      {
        "templateId": "social-post-template",
        "viewportHeight": 1080,
        "viewportWidth": 1080,
        "modifications": [
          {
            "heading": "Summer Sale",
            "tagline": "Up to 50% off",
            "bgColor": "#3357FF"
          }
        ]
      }
    ]
  })
};
 
fetch('https://api.ojo.so/v1/image/bulk', 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/bulk",
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([
'defaultOptions' => [
'viewportWidth' => 1200,
'viewportHeight' => 630,
'transparentBackground' => false
],
'templates' => [
[
'templateId' => 'product-card-template',
'modifications' => [
[
'title' => 'Premium Headphones',
'price' => '$199.99',
'color' => '#FF5733'
],
[
'title' => 'Wireless Earbuds',
'price' => '$89.99',
'color' => '#33FF57'
]
]
],
[
'templateId' => 'social-post-template',
'viewportHeight' => 1080,
'viewportWidth' => 1080,
'modifications' => [
[
'heading' => 'Summer Sale',
'tagline' => 'Up to 50% off',
'bgColor' => '#3357FF'
]
]
]
]
]),
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/bulk"
  payload := strings.NewReader(`{
    "defaultOptions": {
      "viewportWidth": 1200,
      "viewportHeight": 630,
      "transparentBackground": false
    },
    "templates": [
      {
        "templateId": "product-card-template",
        "modifications": [
          {
            "title": "Premium Headphones",
            "price": "$199.99",
            "color": "#FF5733"
          },
          {
            "title": "Wireless Earbuds",
            "price": "$89.99",
            "color": "#33FF57"
          }
        ]
      },
      {
        "templateId": "social-post-template",
        "viewportHeight": 1080,
        "viewportWidth": 1080,
        "modifications": [
          {
            "heading": "Summer Sale",
            "tagline": "Up to 50% off",
            "bgColor": "#3357FF"
          }
        ]
      }
    ]
  }`)
 
  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  \"defaultOptions\": {\n    \"viewportWidth\": 1200,\n    \"viewportHeight\": 630,\n    \"transparentBackground\": false\n  },\n  \"templates\": [\n    {\n      \"templateId\": \"product-card-template\",\n      \"modifications\": [\n        {\n          \"title\": \"Premium Headphones\",\n          \"price\": \"$199.99\",\n          \"color\": \"#FF5733\"\n        },\n        {\n          \"title\": \"Wireless Earbuds\",\n          \"price\": \"$89.99\",\n          \"color\": \"#33FF57\"\n        }\n      ]\n    },\n    {\n      \"templateId\": \"social-post-template\",\n      \"viewportHeight\": 1080,\n      \"viewportWidth\": 1080,\n      \"modifications\": [\n        {\n          \"heading\": \"Summer Sale\",\n          \"tagline\": \"Up to 50% off\",\n          \"bgColor\": \"#3357FF\"\n        }\n      ]\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.ojo.so/v1/image/bulk")
  .method("POST", body)
  .addHeader("Authorization", "Bearer <your API key>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Response

200

Your images are generated. An image that failed to generate is listed in errors with its reason, and the others are returned. errors is left out when every image was generated.


{
  "images": [
    {
      "id": "image-id-1",
      "templateId": "product-card-template",
      "imageUrl": "https://example.com/path/to/image1.png",
      "createdAt": "2023-08-29T12:34:56Z"
    },
    {
      "id": "image-id-3",
      "templateId": "social-post-template",
      "imageUrl": "https://example.com/path/to/image3.png",
      "createdAt": "2023-08-29T12:34:58Z"
    }
  ],
  "errors": [
    {
      "templateId": "product-card-template",
      "modify": {
        "title": "Wireless Earbuds",
        "price": "$89.99",
        "color": "#33FF57"
      },
      "error": "Failed to generate image",
      "logs": ["Error detail information"]
    }
  ],
  "totalRequested": 3,
  "successCount": 2,
  "failureCount": 1
}

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. Update necessary fields and try again. logs says why: a templateId that is not one of your templates, a missing templates array or templateId, an empty modifications array, or more than 50 images in the request.


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

Limitations

Maximum Batch Size: You can generate up to 50 images in a single batch request across all templates combined.
Rendered HTML: at most 5 MB per image and 25 MB for the whole request. A larger request gets a 422 before anything renders.
Partial results: an image that fails or is not done within 90 seconds is listed in errors with its reason. The other images are returned. Only they cost credits, and each failed image costs nothing.
Credit Consumption: Each image generated in the batch consumes 1 credit.
Rate Limiting: Bulk requests are subject to the same rate limits as individual requests. See rate limits for details.