orshot 0.2.0

Orshot API SDK for Python.

Orshot API Python SDK

View on pypi.org: pypi.org/project/orshot

Installation

pip install orshot

Usage

If you don't have your API key, get one from orshot.com.

Initialise

import orshot

os = orshot.Orshot('YOUR_ORSHOT_API_KEY')

render_from_studio_template

Render from a custom Studio template. Supports image, PDF, video generation and publishing to social accounts.

Generate Image

response = os.render_from_studio_template({
    'template_id': 1234,
    'modifications': {
        'title': 'Orshot Studio',
        'description': 'Generate images from custom templates',
    },
    'response': { 'type': 'url', 'format': 'png', 'scale': 2 },
})

Generate PDF

response = os.render_from_studio_template({
    'template_id': 1234,
    'modifications': { 'title': 'Invoice #1234' },
    'response': { 'type': 'url', 'format': 'pdf' },
    'pdf_options': {
        'margin': '20px',
        'range_from': 1,
        'range_to': 2,
        'color_mode': 'rgb',
        'dpi': 300,
    },
})

Generate Video

response = os.render_from_studio_template({
    'template_id': 1234,
    'modifications': {
        'videoElement': 'https://example.com/custom-video.mp4',
        'videoElement.trimStart': 0,
        'videoElement.trimEnd': 10,
    },
    'response': { 'type': 'url', 'format': 'mp4' },
    'video_options': { 'trim_start': 0, 'trim_end': 20, 'muted': False, 'loop': True },
})

Publish to Social Accounts

response = os.render_from_studio_template({
    'template_id': 1234,
    'modifications': { 'title': 'Check out our latest update!' },
    'response': { 'type': 'url', 'format': 'png' },
    'publish': {
        'accounts': [1, 2],
        'content': 'Check out our latest design!',
    },
})
# response['publish'] => [{'platform': 'twitter', 'username': 'acmehq', 'status': 'published'}, ...]

Schedule a Post

response = os.render_from_studio_template({
    'template_id': 1234,
    'modifications': { 'title': 'Scheduled post' },
    'response': { 'type': 'url', 'format': 'png' },
    'publish': {
        'accounts': [1],
        'content': 'This will be posted later!',
        'schedule': { 'scheduled_for': '2026-04-01T10:00:00Z' },
        'timezone': 'America/New_York',
    },
})

Parameters

argument	required	description
template_id	Yes	ID of the Studio template (integer).
modifications	No	Dict of dynamic modifications for the template.
response.type	No	base64, binary, url (Defaults to url).
response.format	No	png, webp, jpg, jpeg, pdf, mp4, webm, gif (Defaults to png).
response.scale	No	Scale of the output (1 = original, 2 = double). Defaults to 1.
response.include_pages	No	Page numbers to render for multi-page templates (e.g. [1, 3]).
response.file_name	No	Custom file name (without extension). Works with url and binary types.
pdf_options	No	{ margin, range_from, range_to, color_mode, dpi }
video_options	No	{ trim_start, trim_end, muted, loop }
publish.accounts	No	List of social account IDs from your workspace.
publish.content	No	Caption/text for the social post.
publish.is_draft	No	True to save as draft instead of publishing.
publish.schedule.scheduled_for	No	ISO date string to schedule the post.
publish.timezone	No	Timezone string (e.g. "America/New_York").
publish.platform_options	No	Per-account options keyed by account ID.

---

render_from_template

Render from a pre-built Orshot template.

response = os.render_from_template({
    'template_id': 'open-graph-image-1',
    'modifications': { 'title': 'Hello World' },
    'response_type': 'url',
    'response_format': 'png',
})

argument	required	description
template_id	Yes	ID of the template (open-graph-image-1, tweet-image-1, etc.)
modifications	Yes	Modifications for the selected template.
response_type	No	base64, binary, url (Defaults to url).
response_format	No	png, webp, pdf, jpg, jpeg (Defaults to png).

For available templates and their modifications refer Orshot Templates Page

generate_signed_url

Generate a signed URL for a template.

response = os.generate_signed_url({
    'template_id': 'open-graph-image-1',
    'modifications': { 'title': 'Hello World' },
    'expires_at': 1744276943,
    'render_type': 'images',
    'response_format': 'png',
})

argument	required	description
template_id	Yes	ID of the template.
modifications	Yes	Modifications for the selected template.
expires_at	Yes	Expires at time in UNIX timestamp (Integer).
render_type	No	images, pdfs (Defaults to images).
response_format	No	png, webp, pdf, jpg, jpeg (Defaults to png).

Local development and testing

Install uv - https://docs.astral.sh/uv/getting-started/installation/#installation-methods

uv venv to create the virtual environment.

Uninstall before building and installing again

uv pip uninstall orshot

Build

python -m build

To install the package locally for testing

uv pip install dist/orshot-0.2.1-py3-none-any.whl

You can create a test.py file with a sample code to render an image.