What is a dynamic URL?

A signed URL that renders an image on request. Change the query parameters and the image changes. No API call.

Updated

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|jpg|jpeg|webp|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|jpg|jpeg|webp|avif|pdf}?page=2&templateId={TEMPLATE_ID}&{PARAMETERS}&sign={SIGNATURE}

Parameters#

  • filename.extension - The file name and extension. The extension sets the output format (e.g., my-image.png, photo.jpg, 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= - Sets quality from 1 (lowest) to 100 (highest) for JPG, WebP and AVIF output. Other formats return an error if you pass it
  • &size= - Smart Resize the output to any size — a preset slug (e.g. instagram-story) or a WIDTHxHEIGHT string (e.g. 1080x1920). The layout adapts to the new canvas automatically
  • &lang= - Language of the text as a language tag (e.g. el, ja, tr). Optional; see Set the text language. If your template has its own parameter named lang, the value goes to that parameter instead
  • {parameter} - Any parameter from your template, such as text, an image URL or a color

Example#

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

Add &size= to render the same template at any size — the layout adapts automatically:

https://api.orshot.com/v1/studio/dynamic-url/story.png?templateId=123&title=Hello%20World&sign=abc123def456&size=instagram-story

Setting Up Dynamic URLs#

1. Enable Dynamic URLs#

Open the template's Connect sheet, go to the Dynamic URL tab and turn on Enable Dynamic Url.

2. Configure Security Settings#

Credit Limit

The most credits this URL can spend. Each render costs 1 credit, so this is also the number of times the URL can be used. Leave empty for unlimited.

Cache Duration (in seconds)

Keep each render for this many seconds, so repeat requests with the same parameters are served faster. Leave it empty for the 5 minute default. Cached hits are not re-rendered, so they spend no credits and do not count toward Credit Limit.

Expires At

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#

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#

HTML
<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:

JavaScript
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 credit limits to prevent abuse
  • Reset signatures if unintended access consumes your Orshot credits

Limitations#

  • Cannot pass values containing the # character
  • URL length limits apply (typically ~2000 characters)
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required