Stillframe

Get started API reference What it can picture Plans and limits Using the picture When a feed fails Paying

Get started

A feed in a few minutes. Pick the kind that matches what you want a picture of.

Every example uses your API key in the KEY variable. You get a key when you subscribe (pricing); it is shown once, right after PayPal sends you back: keep it somewhere safe. Keys start with sf_live_. Send the key in the X-API-Key header, and keep it out of web pages and public repositories: anyone who has it can change your feeds.

export KEY=sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each example makes a feed and prints it back. The image_url in the answer is the feed's permanent address. Open it in a browser or put it in an img tag (see Using the picture). It needs no key.

A page

For a web page or dashboard that is on the public internet. Stillframe opens it in a real browser, waits for it to stop loading, and takes the picture.

curl -s -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"kind":"page","name":"Sales board","url":"https://example.com/board","refresh_s":900}' \
  https://stillframe.us/api/feeds

The answer:

{"id": 1, "name": "Sales board", "kind": "page", "url": "https://example.com/board",
 "canvas": "1920x1080", "canvas_in_use": "1920x1080", "background": "#000000", "format": "png", "refresh_s": 900, "refresh_in_use_s": 900,
 "wait_s": 1.0, "timezone": "UTC", "allow_blank": false, "enabled": true,
 "image_url": "https://stillframe.us/f/bktjrvfovxh66x4wndcpn4plzu.png",
 "status": {"state": "pending", "last_ok_at": null, "last_attempt_at": null, "error": null,
            "detail": null, "partial": false, "lag_s": 0, "render_ms": null, "bytes": 0, "version": 0}}

The state is pending until the first picture is taken. A new feed is picked up within a few seconds, and a page render is cut off after 44 seconds. Until then the address answers 404 with no_image_yet. To take the first picture now:

curl -s -X POST -H "X-API-Key: $KEY" https://stillframe.us/api/feeds/1/render

Then ask how it went:

curl -s -H "X-API-Key: $KEY" https://stillframe.us/api/feeds/1

When status.state is ok, the address shows the picture. If it says failing, the error field names the reason; When a feed fails explains each one.

A camera

For a camera that is reachable from the internet and speaks RTSP, or serves an MJPEG stream over http or https. Stillframe takes one frame each time. Put the user and password in the address if the camera needs them, as in the example. Answers show the user and password as ***, and every value after a ? as *** (details).

curl -s -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"kind":"camera","name":"Yard","url":"rtsp://viewer:[email protected]:554/live"}' \
  https://stillframe.us/api/feeds

A camera feed makes a JPEG at the frame's own size unless you choose a canvas. Which streams work, and which do not, is on What it can picture.

A picture you push

For anything Stillframe cannot reach: a dashboard on your own network, a camera behind a router, a chart your script draws. You make a push feed, then send it pictures whenever you like. The feed serves the last one you sent.

curl -s -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"kind":"push","name":"Office dashboard"}' \
  https://stillframe.us/api/feeds

curl -s -X PUT -H "X-API-Key: $KEY" --data-binary @board.png \
  https://stillframe.us/api/feeds/3/image

Use the id from the first answer in place of 3. A successful push answers with the stored size and the address:

{"stored": true, "width": 1920, "height": 1080, "bytes": 184233,
 "image_url": "https://stillframe.us/f/y2z6xsccszpbf5jn3dls5phgma.png", "version": 1}

The picture must be a PNG or JPEG. Stillframe reads what the file really is, not what you call it. Sending from a schedule (cron, a Windows scheduled task) is shown on How it works. How often you may push depends on your plan: see Plans and limits.

Next

Change a feed, sending only what changes (the example makes feed 1 refresh every hour):

curl -s -X PATCH -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"refresh_s":3600}' https://stillframe.us/api/feeds/1