REST API · v1

A REST API built for developers.

Authenticated, typed, and blazing fast. Integrate in minutes, scale to millions.

Read Docs Get API Key
terminal
$ curl -X POST https://api.picstream.io/v1/generate/image \
-H "Authorization: Bearer ps_live_sk_..." \
-d '{"template":"og-card","data":{...}}'
{
"url": "https://cdn.picstream.io/img/f3a9c2b1.png",
"cached": true,
"render_ms": 47
}
▌

Bearer token authentication

Every request is authenticated with an API key in the Authorization header. Keys are scoped to specific operations so you can safely delegate access.

Authorization: Bearer ps_live_sk_xxxxxxxxxxx
Live keys — prefixed ps_live_, for production use
Test keys — prefixed ps_test_, no charges, watermarked output
Production Key
Created Jun 1, 2025
Active
ps_live_xxxx••••••••••••xxxx
Scopes
readwritetemplates:readrenders:write
ExpiresNever

Endpoints

Simple, predictable, REST-ful.

POST/api/v1/generate/image

Generate a PNG or WebP image from a template and data payload.

200 OK
POST/api/v1/generate/pdf

Render a print-ready PDF document. Supports multi-page layouts.

202 Accepted
GET/api/v1/renders/:jobId

Poll the status of an async render job. Returns URL when complete.

200 OK

Works in any language

It's just HTTP. Call it from cURL, JavaScript, Python, Ruby, Go, or PHP — anything that can make a POST request can generate images with PicStream.

No SDK lock-in
Consistent JSON schema
Typed response bodies
OpenAPI 3.1 spec available
curl -X POST https://api.picstream.io/v1/generate/image \
  -H "Authorization: Bearer ps_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "og-card-dark",
    "format": "png",
    "width": 1200,
    "height": 630,
    "data": {
      "title": "Introducing PicStream 2.0",
      "subtitle": "Image generation at any scale",
      "theme": "dark"
    }
  }'

Two response modes

Fast renders return synchronously. Heavy jobs go async and are polled via a job URL.

202 AcceptedAsync render

Returned for heavy templates. Poll poll_url until status is "complete".

{
  "job_id": "job_f3a9c2b1",
  "status": "queued",
  "poll_url": "https://api.picstream.io
    /v1/renders/job_f3a9c2b1",
  "estimated_ms": 250
}
200 OKCache hit

Identical requests return cached results immediately — no re-render, sub-millisecond response.

{
  "url": "https://cdn.picstream.io
    /img/f3a9c2b1.png",
  "cached": true,
  "render_ms": 47,
  "expires_at": "2025-07-01T00:00:00Z"
}

Status codes

Predictable responses for every scenario.

200
OK

Image rendered and URL returned.

202
Accepted

Async job queued. Poll for result.

401
Unauthorized

Missing or invalid API key.

404
Not Found

Template ID does not exist.

429
Rate Limited

Slow down. Retry after header set.

Get your API key free

1,000 images per month on the free plan. No credit card. Start generating in under 5 minutes.

Get API Key Free Read the Docs