# Image Generation

> Generate PNG, JPEG, WebP, and AVIF images from your templates via the API — single images or multi-page carousels

- **URL**: https://orshot.com/docs/image-generation

---

Orshot makes it easy to generate images programmatically from your Studio templates. Pass in your content, get back a production-ready image — as a URL, Base64 string, or binary stream.

## Quick Start

To generate an image, make a `POST` request to the render endpoint with your template ID and any content modifications.```javascript
const response = await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <YOUR_API_KEY>",
  },
  body: JSON.stringify({
    templateId: "<YOUR_TEMPLATE_ID>",
    modifications: {
      title: "Welcome to Orshot",
      subtitle: "Generate images at scale",
      logo: "https://example.com/logo.png",
    },
    response: {
      format: "png",
      type: "url",
    },
  }),
});

const data = await response.json();
console.log(data.data.content); // Image URL
```## How It Works

1. **Design a template** in [Orshot Studio](https://orshot.com/docs/orshot-studio) with parameterized elements (text, images, shapes)
2. **Call the API** with your template ID and pass the values you want to override in `modifications`
3. **Receive your image** as a hosted URL, Base64 string, or binary data

## API Request Structure

| Field                   | Type     | Required | Description                                                      |
| :---------------------- | :------- | :------- | :--------------------------------------------------------------- |
| `templateId`            | `string` | Yes      | Your Studio template ID                                          |
| `modifications`         | `object` | No       | Key-value pairs to override template content                     |
| `response.format`       | `string` | No       | Output format: `png`, `jpeg`, `webp`, or `avif` (default: `png`) |
| `response.type`         | `string` | No       | Response type: `url`, `base64`, or `binary` (default: `url`)     |
| `response.scale`        | `number` | No       | Scale factor for output size (default: `1`)                      |
| `response.includePages` | `array`  | No       | Specific pages to render for multi-page templates                |
| `response.fileName`     | `string` | No       | Custom filename for the output (without extension)               |

## Response

When `type` is set to `url`, you receive a hosted image URL:```json
{
  "data": {
    "content": "https://storage.orshot.com/cloud/renders/images/abc123.png",
    "renders": 1,
    "mimeType": "image/png"
  }
}
```When `type` is set to `base64`:```json
{
  "data": {
    "content": "data:image/png;base64,iVBORw0KGgo...",
    "renders": 1,
    "mimeType": "image/png"
  }
}
```## Modifying Template Content

Use the `modifications` object to override any parameterized element in your template. The key is the parameter name you assigned in Studio, and the value is the new content.

### Text Elements```json
{
  "modifications": {
    "title": "Your Custom Title",
    "subtitle": "A short description",
    "price": "$29.99"
  }
}
```### Image Elements

Pass a URL to replace image elements:```json
{
  "modifications": {
    "avatar": "https://example.com/photo.jpg",
    "background": "https://example.com/bg.png",
    "logo": "https://example.com/logo.svg"
  }
}
```### Canvas Background

Override the entire canvas background color or image:```json
{
  "modifications": {
    "canvasBackgroundColor": "#1a1a2e",
    "canvasBackgroundImage": "https://example.com/bg-pattern.png"
  }
}
```The `canvasBackgroundColor` supports HEX, RGBA, and CSS gradients:```json
{
  "modifications": {
    "canvasBackgroundColor": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
  }
}
```## Scaling Output

Use `response.scale` to control the output resolution. This is useful when you need higher resolution images for print or retina displays.```json
{
  "response": {
    "format": "png",
    "type": "url",
    "scale": 2
  }
}
```| Scale | Result                                |
| :---- | :------------------------------------ |
| `1`   | Original template size (default)      |
| `2`   | 2x resolution (double width & height) |
| `3`   | 3x resolution                         |

## Example: Social Media Post```javascript
const response = await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <YOUR_API_KEY>",
  },
  body: JSON.stringify({
    templateId: "<SOCIAL_POST_TEMPLATE>",
    modifications: {
      headline: "10 Tips for Better Productivity",
      author_name: "Jane Smith",
      author_avatar: "https://example.com/jane.jpg",
      "author_name.color": "#ffffff",
      canvasBackgroundColor: "#0f172a",
    },
    response: {
      format: "png",
      type: "url",
    },
  }),
});
```## What's Next