The official SDKs handle authentication, retries and response parsing for
you. Read SDKs before writing HTTP calls by hand.
Base URL
Every request goes to a single host.Authentication
Every request carries an API key in thex-api-key header. Keys begin with
sm_.
Responses
A successful response carriessuccess: true and a data object. A failure
carries the same envelope on every endpoint, so you branch on error_code
once rather than per endpoint.
Errors holds every
error_code behind these statuses and a retry
loop you can copy.
Rate limits
The sustained rate is 1,000 requests per minute, and a separate ceiling counts how many renders run at once. Both answer with a429, and error.type tells
them apart: slow down, or wait for work already in flight.
Usage limits holds the concurrency numbers per
plan and the headers that report both ceilings on every response.
Synchronous and asynchronous
A render returns the finished image atdata.print_files[0].export_path. Send
is_async: true and the same call returns a job_id instead, which you poll
at GET /api/v1/jobs/{job_id} or receive over a
webhook.
Pagination covers how the list endpoints hand back the
next page.
Versioning
The API is versioned in the path, andv1 is current. Paths that carried an
earlier name still answer under it and are marked deprecated in the spec.
Legacy paths maps the older spellings.
Frequently asked
Which endpoints can I call from a browser?
Which endpoints can I call from a browser?
None of them. A key with the
sm_ prefix is a server credential, and a
key that reaches a browser bundle should be treated as leaked. Put the
call behind your own route and keep the key on the server.Do I have to poll for an async render?
Do I have to poll for an async render?
No. A webhook carries the finished render to you, so
polling
GET /api/v1/jobs/{job_id} is the fallback rather than the
expected path.Does a failed render cost credits?
Does a failed render cost credits?
No. A render that never produced an image is refunded to the balance it
was drawn from.
How do I keep a retry from rendering twice?
How do I keep a retry from rendering twice?
Send an
Idempotency-Key on the upload. Reusing the same key with a
different body answers 409 rather than creating a second template.