Dynamic URLs

Dynamic URLs allow you to generate images from Studio templates by passing parameters directly in the URL. This feature enables you to create dynamic images without making API calls, perfect for embedding in emails, social media, or any context where you need on-the-fly image generation

How It Works#

Dynamic URLs work by encoding template modifications as URL parameters. When accessed, the URL automatically generates an image with the specified modifications applied to your Studio template

Video demo:

URL Structure#

For Single page templates#

https://api.orshot.com/v1/studio/dynamic-url/{filename}.{png|webp|jpeg|avif|pdf}?templateId={TEMPLATE_ID}&{PARAMETERS}&sign={SIGNATURE}

For Multi-page templates#

For multi-page templates, you can pass &page=2 parameter to generate from a specific page. Make sure to pass page specific parameters relevant to the page for dynamic values, for.eg &page2@heading=Custom Title&page2@image=https://domain.com/image.png

https://api.orshot.com/v1/studio/dynamic-url/{filename}.{png|webp|jpeg|avif|pdf}?page=2&templateId={TEMPLATE_ID}&{PARAMETERS}&sign={SIGNATURE}

Parameters#

• filename.extension - Specify the desired filename and extension for the generated output (e.g., my-image.png, report.pdf)
• &templateId= - Your Studio template ID (required)
• &page= - Page number you want to render(for multi-page templates only)
• &sign= - Security signature to authorize access (required)
• &quality= - control quality of JPEG images only, 10 being lowest and 100 being highest quality
• {modification_key} - Any text-type modification from your template

Example#

https://api.orshot.com/v1/studio/dynamic-url/hello-world.png?templateId=123&title=Hello%20World&subtitle=Welcome&sign=abc123def456

Setting Up Dynamic URLs#

1. Enable Dynamic URLs#

Navigate to your Studio template's playground and go to the "Dynamic URL" tab. Toggle "Enable Dynamic URL" to activate this feature.

2. Configure Security Settings#

Max Renders Allowed

Set a limit on how many times the URL can be used. Leave empty for unlimited renders.

Expiration Time

Control how long the URL remains valid:

• 1 hour
• 12 hours
• 1 day
• 3 days
• 1 month
• 1 year
• Never expire

Security Signature

Each dynamic URL includes a unique signature (sign parameter) that authorizes access. You can:

• Copy the current signature
• Reset to generate a new signature (invalidates the old one)

Usage Examples#

Basic Text Replacement#

If your template has text modifications named title and subtitle:

https://api.orshot.com/v1/studio/dynamic-url/dynamic-title.jpg?templateId=123&title=Dynamic%20Title&subtitle=Custom%20Subtitle&sign=your_signature

In HTML#

<img
  src="https://api.orshot.com/v1/studio/dynamic-url/welcome-image.png?templateId=123&title=Welcome&sign=your_signature"
  alt="Dynamic Image"
/>

In Email Templates#

<img
  src="https://api.orshot.com/v1/studio/dynamic-url/user-card.jpg?templateId=123&name={{user.name}}&date={{current_date}}&sign=your_signature"
/>

Best Practices#

URL Encoding#

Always encode parameter values to handle special characters:

const encodedTitle = encodeURIComponent("Hello & Welcome!");
const url = `https://api.orshot.com/v1/studio/dynamic-url/welcome-banner.png?templateId=123&title=${encodedTitle}&sign=your_signature`;

Security Considerations#

• Set appropriate expiration times for time-sensitive content
• Use render limits to prevent abuse
• Reset signatures if unintended access consumes your Orshot renders

Limitations#

• Cannot pass values containing the # character
• URL length limits apply (typically ~2000 characters)