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
| Option | Values | Default |
|---|---|---|
style | natural, bright, warm, vivid, house (Pro+) | natural |
vertical_correction | true / false | true |
sky | auto / off | auto |
window_pull | true / false | true |
facade_air | true / false | false |
privacy_blur | off / faces_plates | off |
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).
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_json | The body is not valid JSON. |
| 401 | missing_api_key | No key sent. Use "Authorization: Bearer <key>". |
| 401 | invalid_api_key | The key is malformed, unknown, expired or revoked. |
| 402 | insufficient_credits | Not enough credits for every image in the job. Nothing was charged. |
| 403 | insufficient_scope | The key lacks the scope this endpoint needs. |
| 403 | feature_not_in_plan | The option requested is not included in your plan. |
| 403 | origin_not_allowed | Publishable key used from an origin not on its allow-list. |
| 403 | organization_suspended | The workspace is suspended. Contact support. |
| 404 | not_found | No such route. Check the method and path against the OpenAPI spec. |
| 404 | job_not_found | No job with that id in this workspace. |
| 404 | image_not_found | No image with that id in this workspace. |
| 404 | webhook_not_found | No webhook endpoint with that id. |
| 404 | organization_not_found | The sub-account does not exist or is not yours. |
| 409 | idempotency_conflict | The Idempotency-Key was already used with a different body. |
| 409 | job_not_cancelable | The job already finished. |
| 413 | payload_too_large | Body too large. Send files with POST /v1/uploads instead. |
| 415 | unsupported_media_type | Content-Type not accepted for this endpoint. |
| 422 | validation_error | A field is missing or invalid; see "errors" for the path of each one. |
| 422 | invalid_cursor | The pagination cursor is not one we issued. |
| 422 | invalid_idempotency_key | Idempotency-Key must be 1-200 visible ASCII characters. |
| 422 | nothing_to_retry | The job has no failed images to retry. |
| 422 | too_many_webhooks | Webhook endpoint limit reached for this workspace. |
| 422 | upload_not_found | The upload_id does not exist in this workspace. |
| 422 | upload_expired | Uploads expire 24 h after creation if unused. |
| 422 | upload_already_used | Each upload can be used in one job only. |
| 422 | upload_missing_file | No bytes were PUT to the upload_url yet. |
| 422 | upload_too_large | The uploaded file exceeds the size limit. |
| 429 | rate_limited | Per-key request limit reached. Wait Retry-After seconds. Retryable. |
| 500 | internal_error | Our fault. Retry with backoff; quote X-Request-Id to support. Retryable. |
| 503 | service_unavailable | Temporary outage of a dependency. Retry with backoff. Retryable. |
| Plan | Requests / min / key | API keys |
|---|---|---|
| Free | 10 | 1 |
| Starter | 60 | 3 |
| Pro | 300 | 10 |
| Scale | 1,200 | 50 |
| Enterprise | 6,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 onjob.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.