ShotEdit API

Send property photos, get listing-ready images back in seconds. REST + JSON, signed webhooks, idempotent retries, OpenAPI 3.1.

Quickstart

1. Create a secret key in API & webhooks. Use a test key while you build: it is free and watermarks the output.

2. Create a job with image URLs:

curl https://api.shotedit.com/v1/jobs \
  -H "Authorization: Bearer $SHOTEDIT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: listing-ABC-123" \
  -d '{
    "images": [{ "url": "https://example.com/living.jpg" }, { "url": "https://example.com/facade.jpg" }],
    "options": { "style": "natural", "sky": "auto", "privacy_blur": "faces_plates" },
    "webhook_url": "https://example.com/hooks/shotedit",
    "metadata": { "listing_id": "ABC-123" }
  }'

The response is 202 Accepted with the job and its images in queued state.

3. Get the result: wait for the job.completed webhook, or poll GET /v1/jobs/{id}. Each image has an output_url (signed, valid 1 hour; fetch the job again for a fresh one).

import { ShotEdit } from '@shotedit/sdk';
const rl = new ShotEdit({ apiKey: process.env.SHOTEDIT_KEY });
const job = await rl.jobs.create({ images: [{ url }] }, { idempotencyKey: 'listing-ABC-123' });
const done = await rl.jobs.waitFor(job.id);
console.log(done.images[0].output_url);

Uploading local files

Photos never pass through our API servers. Ask for a signed URL, PUT the bytes, then reference the upload:

POST /v1/uploads { "content_type": "image/jpeg", "filename": "kitchen.jpg" }
→ 201 { "id": "…", "upload_url": "https://…", "method": "PUT", "headers": { "content-type": "image/jpeg" } }

PUT <upload_url>  (raw bytes, same Content-Type)

POST /v1/jobs { "images": [{ "upload_id": "…" }] }

Webhooks

Events: job.completed (all images finished; status is completed or partial), job.failed, image.completed, image.failed. Register endpoints in the dashboard or with POST /v1/webhooks; a per-job webhook_url is signed with your workspace signing secret.

Every delivery carries ShotEdit-Signature: t=<unix>,v1=<hex>, where v1 = HMAC_SHA256(secret, t + "." + rawBody). Verify on the raw body, reject timestamps older than 5 minutes, and answer 2xx quickly. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. Use the event id to deduplicate.

import { verifyWebhook } from '@shotedit/sdk';
app.post('/hooks/shotedit', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyWebhook(req.body.toString(), req.get('ShotEdit-Signature'), process.env.SHOTEDIT_WHSEC)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  if (event.type === 'job.completed') queueDownload(event.data.id);
  res.sendStatus(200);
});

Edit options

OptionValuesDefault
stylenatural, bright, warm, vivid, house (Pro+)natural
vertical_correctiontrue / falsetrue
skyauto / offauto
window_pulltrue / falsetrue
facade_airtrue / falsefalse
privacy_bluroff / faces_platesoff
output{ format: jpeg|webp, quality: 60-100, max_width }jpeg, 92

Defaults can be set per workspace in Settings. The edit is non-generative: it corrects light, color and geometry and never adds or removes objects. Outputs carry XMP metadata stating they were edited, and the original stays downloadable.

Errors, limits and idempotency

Errors use RFC 9457 (application/problem+json): { type, title, status, code, detail }, plus errors[] with the path of each invalid field on validation_error. Switch on code, never on detail. Only 429, 500 and 503 are worth retrying (exponential backoff with jitter, honoring Retry-After).

HTTPcodeMeaning
400invalid_jsonThe body is not valid JSON.
401missing_api_keyNo key sent. Use "Authorization: Bearer <key>".
401invalid_api_keyThe key is malformed, unknown, expired or revoked.
402insufficient_creditsNot enough credits for every image in the job. Nothing was charged.
403insufficient_scopeThe key lacks the scope this endpoint needs.
403feature_not_in_planThe option requested is not included in your plan.
403origin_not_allowedPublishable key used from an origin not on its allow-list.
403organization_suspendedThe workspace is suspended. Contact support.
404not_foundNo such route. Check the method and path against the OpenAPI spec.
404job_not_foundNo job with that id in this workspace.
404image_not_foundNo image with that id in this workspace.
404webhook_not_foundNo webhook endpoint with that id.
404organization_not_foundThe sub-account does not exist or is not yours.
409idempotency_conflictThe Idempotency-Key was already used with a different body.
409job_not_cancelableThe job already finished.
413payload_too_largeBody too large. Send files with POST /v1/uploads instead.
415unsupported_media_typeContent-Type not accepted for this endpoint.
422validation_errorA field is missing or invalid; see "errors" for the path of each one.
422invalid_cursorThe pagination cursor is not one we issued.
422invalid_idempotency_keyIdempotency-Key must be 1-200 visible ASCII characters.
422nothing_to_retryThe job has no failed images to retry.
422too_many_webhooksWebhook endpoint limit reached for this workspace.
422upload_not_foundThe upload_id does not exist in this workspace.
422upload_expiredUploads expire 24 h after creation if unused.
422upload_already_usedEach upload can be used in one job only.
422upload_missing_fileNo bytes were PUT to the upload_url yet.
422upload_too_largeThe uploaded file exceeds the size limit.
429rate_limitedPer-key request limit reached. Wait Retry-After seconds. Retryable.
500internal_errorOur fault. Retry with backoff; quote X-Request-Id to support. Retryable.
503service_unavailableTemporary outage of a dependency. Retry with backoff. Retryable.
PlanRequests / min / keyAPI keys
Free101
Starter603
Pro30010
Scale1,20050
Enterprise6,000+unlimited

Each response includes RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and X-Request-Id. A retried POST /v1/jobs with the same Idempotency-Key and body returns the original job (header Idempotent-Replayed: true) and is never charged twice.

Versioning, pagination and reliability

Base URL https://api.shotedit.com/v1 (also served at https://shotedit.com/api/v1). Within v1 we only make additive changes: new endpoints, new optional fields, new event types and new error codes. Ignore unknown fields. Breaking changes ship as /v2, with at least 12 months of overlap.

Pagination: list endpoints take limit (1-100, default 20) and return { object: "list", data, has_more, next_cursor }. Pass next_cursor back as cursor until has_more is false. Cursors are stable while new items arrive.

Request IDs: every response carries X-Request-Id (send your own, 8-128 characters of [A-Za-z0-9._:-], to trace a call end to end). Server-Timing shows time spent on our side.

Status: GET https://api.shotedit.com/v1/health needs no key and answers 200 with each component (ok, degraded) or 503 when the API cannot serve requests. Human view: status page.

CORS: secret keys are for servers only. Browsers use publishable keys (se_pub_…) restricted to the origins you list; rate-limit and request-id headers are exposed to them.

Test mode

Keys starting with se_test_ create jobs in the test environment: no credits are used and outputs are watermarked. Everything else (webhooks, limits, errors) behaves like live.

Integrations

  • SDKs: JavaScript/TypeScript (@shotedit/sdk) and Python (shotedit).
  • Embeddable widget for any website or intranet, with a publishable key restricted to your domains:
    <script src="https://shotedit.com/widget/v1.js" data-key="se_pub_live_…" async></script>
    <div data-shotedit-uploader data-style="natural"></div>
  • WordPress plugin: bulk action "Enhance with ShotEdit" in the Media Library.
  • Zapier / Make: trigger on new files in Dropbox or Google Drive, call POST /v1/jobs, and save outputs on job.completed.

Sub-accounts and pooled billing

Portals, franchise networks and partners can create a sub-account per office, agent or client. Members of the parent account inherit access; with pooled billing, sub-accounts spend the parent's credits and usage is broken down per sub-account. Each sub-account can have its own API keys and webhooks.