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

How it works

A feed is one thing Stillframe keeps a picture of. Each feed has one address that always serves its newest picture.

Three kinds of feed

kind	you give it	Stillframe
page	a web address (http or https)	opens it in a real browser, waits for the page to stop loading, and takes the picture
camera	an RTSP address, or an MJPEG address over http or https, with a user and password if it needs one	takes one frame
push	nothing; you send it pictures	serves the last picture you sent

Page and camera feeds refresh on their own schedule: every 5 minutes at the fastest, once a day at the slowest, depending on your plan. A push feed changes when you send it something.

Size and background

Choose a canvas: 1920x1080, 1080x1920, 3840x2160 or 2160x3840 (the 4K pair is on Standard and Pro). A page is drawn at exactly that size. A camera frame or a picture you send is never enlarged: if it is bigger than the canvas it is shrunk to fit, keeping its shape; if it is smaller it stays its own size in the middle. The space around it is a colour you choose.

Camera and push feeds can also use native: the picture at its own size, shrunk only if it is larger than 4K. That is usually what you want in an email.

Pictures you send are drawn again by Stillframe before they are served, so their hidden details (a phone photo's location, the camera model, comments) are not passed on.

How fresh is the picture

The address is served through a cache, so a viewer may see a picture up to twice the feed's refresh interval old. Email programs can keep their own copy for longer: some show the picture as it was when the email was first opened.

When a picture cannot be taken

The address keeps serving the last good picture, and the dashboard and the API say why the new one failed:

reason	what it means
`http_404`, `http_500`, ...	the page answered with that error. `http_403` usually means the site refuses visitors from data centres.
`timeout`	the page did not answer in time
`blank`	the page loaded but drew nothing (every pixel the same colour). A feed can allow this if blank is right.
`blocked_egress`	the address, or a page it redirects to, is on a private network or is otherwise not allowed
`dns_fail`	the name does not exist
`camera_error`	the camera did not give a frame

A feed that keeps failing is tried less often, waiting twice as long each time, up to an hour. Every reason, and what to do, is on When a feed fails.

The API

Everything the dashboard does, the API does. Send your key in the X-API-Key header. Every route, with its inputs, outputs and errors, is in the API reference.

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

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

request	does
`GET /api/account`	your plan, its limits and what you use
`GET /api/feeds`, `POST /api/feeds`	list, or make one: `kind`, `name`, `url`, `canvas`, `background` (`#rrggbb`), `format` (`png` or `jpg`), `refresh_s`, `wait_s`, `timezone`
`GET`, `PATCH`, `DELETE /api/feeds/{id}`	read, change or remove one
`PUT /api/feeds/{id}/image`	send a PNG or JPEG to a push feed, up to 10 MB
`POST /api/feeds/{id}/render`	take a new picture now (once a minute)
`POST /api/feeds/{id}/retoken`	give the feed a new address; the old one stops working

Image addresses need no key: they are unlisted, not private. Anyone who has one can see the picture, the same as any image on the web. If one gets out, give the feed a new address.

Sending pictures from your own network

For a dashboard or camera that only works inside your network, take the picture there and send it. From a Linux or Mac machine, on a schedule with cron (this one runs every fifth minute):

*/5 * * * * curl -s -X PUT -H "X-API-Key: $KEY" --data-binary @/path/to/picture.png https://stillframe.us/api/feeds/12/image

From Windows, in a scheduled task:

Invoke-RestMethod -Method Put -Uri https://stillframe.us/api/feeds/12/image `
  -Headers @{ "X-API-Key" = $env:STILLFRAME_KEY } -InFile C:\pictures\board.png -ContentType image/png

What it refuses

Addresses on private networks, the machine's own addresses, and ports below 1024 other than 80 and 443.
Files sent to a push feed that are not PNG or JPEG, are over 10 MB, or are over 50 million pixels.
More feeds, faster refreshes or more stored pictures than your plan holds.