Which image format should I use?

Orshot supports four image output formats: PNG, JPEG, WebP and AVIF. Set the format using the response.format field in your API request.

Available Formats#

PNG (Default)#

PNG is the default format. It supports transparency and produces sharp, lossless images — ideal for graphics, logos, and social media posts.

{
  "templateId": "<YOUR_TEMPLATE_ID>",
  "modifications": {
    "title": "Transparent Background Image"
  },
  "response": {
    "format": "png",
    "type": "url"
  }
}

JPEG#

JPEG produces smaller files, which is useful for photo-heavy content like blog featured images or product photos. Transparency is not supported — transparent areas render as white.

{
  "templateId": "<YOUR_TEMPLATE_ID>",
  "modifications": {
    "photo": "https://example.com/product.jpg"
  },
  "response": {
    "format": "jpeg",
    "type": "url"
  }
}

WebP#

WebP balances quality and file size. It supports transparency and typically produces files 25-35% smaller than PNG. Great for web applications where performance matters.

{
  "templateId": "<YOUR_TEMPLATE_ID>",
  "modifications": {
    "banner": "https://example.com/hero.jpg"
  },
  "response": {
    "format": "webp",
    "type": "url"
  }
}

AVIF#

AVIF gives the smallest files and supports transparency. Most modern browsers can show it. Check that the app or platform you send it to accepts AVIF before you use it.

{
  "templateId": "<YOUR_TEMPLATE_ID>",
  "modifications": {
    "banner": "https://example.com/hero.jpg"
  },
  "response": {
    "format": "avif",
    "type": "url"
  }
}

Image Quality#

Use response.quality to set compression for jpeg, webp and avif. It takes a number from 1 to 100. The default is 90 for JPEG and WebP, and 50 for AVIF. Lower values give smaller files. PNG ignores it.

{
  "response": {
    "format": "jpeg",
    "type": "url",
    "quality": 75
  }
}

Response Types#

Regardless of the image format, you can choose how the image is delivered using response.type:

URL#

Returns a hosted URL that you can use directly in your application. The image is stored on Orshot's CDN.

{
  "response": {
    "format": "png",
    "type": "url"
  }
}

Response:

{
  "data": {
    "content": "https://storage.orshot.com/cloud/renders/images/abc123.png"
  }
}

Base64 (Default)#

If you do not set response.type, you get Base64. Returns the image as a Base64-encoded data URI. Useful when you need to embed the image directly, pass it to another service, or process it further.

{
  "response": {
    "format": "png",
    "type": "base64"
  }
}

Response:

{
  "data": {
    "content": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Binary#

Returns the raw image binary data. Best for downloading the image directly or piping it to file storage.

{
  "response": {
    "format": "png",
    "type": "binary"
  }
}

The response will be the raw image bytes with the appropriate Content-Type header.

Controlling Output Size#

Use response.scale to increase the output resolution without changing the template design:

{
  "response": {
    "format": "png",
    "type": "url",
    "scale": 2
  }
}

A template designed at 1200×630px with scale: 2 will output a 2400×1260px image.

Custom Filenames#

Use response.fileName to set a custom filename for the output. This is especially useful when generating images in bulk and organizing them by content.

{
  "response": {
    "format": "png",
    "type": "url",
    "fileName": "social-post-march-2026"
  }
}