Skip to content
OmniscapeRenders API
All pages
  1. Overview
  2. Quick start
  3. Authentication
  4. API reference
    1. GET /media
    2. POST /media
    3. GET /media/{id}/preview
    4. GET /integrations/google/connect
    5. GET /integrations/google
    6. DELETE /integrations/google
    7. GET /integrations/google/folders
    8. POST /media/import
    9. GET /media/imports/{id}
    10. POST /renders
    11. GET /renders/{id}
    12. GET /renders/{id}/download
    13. GET /usage
  5. Code examples
  6. Error handling
  7. Rate limits & quotas
  8. Troubleshooting
  9. Changelog

Tutorial

Quick start

One render, end to end, in four calls. Everything else on this site is detail on one of them.

You need a key with the media:read, renders:create and renders:read scopes, and at least one photo in your workspace. Put the key in your environment as OMNISCAPE_API_KEY and paste this in.

KEY="$OMNISCAPE_API_KEY"

# 1 — find a photo (the render endpoint accepts no URLs, only ids from here)
curl -s "https://omniscape.io/api/v1/media?limit=5" -H "Authorization: Bearer $KEY"

# 2 — start the render
curl -s -X POST "https://omniscape.io/api/v1/renders" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"media_id":"<id from step 1>","quote":"stay soft"}'
# => 202 { "id": "rnd_7ef2da3bde9a", "status": "queued" }

# 3 — poll until status is completed (free, and uncounted against your cap)
curl -s "https://omniscape.io/api/v1/renders/rnd_7ef2da3bde9a" -H "Authorization: Bearer $KEY"

# 4 — download it, with the same header
curl -s "https://omniscape.io/api/v1/renders/rnd_7ef2da3bde9a/download" \
  -H "Authorization: Bearer $KEY" -o render.mp4

# 5 — that link does not expire, and re-downloading is free
Only POST /api/v1/renders costs anything. Reads are free and uncounted against your spend cap: polling a render, downloading the file, re-downloading it a hundred times, listing media, fetching previews, checking usage. Reads are rate limited but never billed, so poll every few seconds rather than continuously: a render takes minutes, so polling harder learns nothing sooner.

What to expect

  • Step 2 returns 202 immediately with an id like rnd_7ef2da3bde9a. That means queued, not started.
  • Step 3 will say queued, then processing, then completed. It takes about 2 minutes. Do not sleep two minutes and check once — poll every few seconds.
  • progress will sit at 0 the whole time and jump to 100 at the end. That is a known defect; drive anything you build off status.
  • Step 4 needs the same Authorization header. The link is on our domain and your key is what authorises it, so it is not something you can paste into a browser.

Then write it properly

A shell loop is fine for a first look and wrong for production: it has no backoff, no deadline, and no idea what to do when a render fails rather than completes. Code examples has the same flow in JavaScript and Python with a poll loop that handles all three of those.