PhotoRescue API

Quickstart

The API turns an image into a repaired or larger one. You create a job, wait for it to finish (by polling or by webhook) and download the result. This takes three steps.

1. 1

   Get an API key

   You need an active business plan (API Starter, Growth or Scale). Create a key in the dashboard under API keys. The key is shown once; store it in a secret manager or an environment variable, never in client-side code.

2. 2

   Create your first job

   Send the image as a public HTTPS link (input.url) or as a file you uploaded first (input.upload_id, see uploads), and choose a model with task. The API answers 202 with the job. Credits are charged now and refunded if the job fails.

   Copy

   curl -X POST https://www.photo-rescue.com/api/v1/jobs \
     -H "Authorization: Bearer $PHOTORESCUE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"task":"upscale","input":{"url":"https://example.com/photos/shoe.jpg"}}'

3. 3

   Get the result

   Poll GET /v1/jobs/{id} until status is succeeded, or receive a webhook. output.url is a signed link that expires in one hour. Results are deleted after 24 hours.

A complete example

This script creates a job, polls it every two seconds and saves the result. Set PHOTORESCUE_API_KEY first.

export PHOTORESCUE_API_KEY="pr_live_your_key_here"

# 1. Create a job
curl -X POST https://www.photo-rescue.com/api/v1/jobs \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"upscale","input":{"url":"https://example.com/photos/shoe.jpg"}}'

# 2. Check it (use the "id" from the response)
curl https://www.photo-rescue.com/api/v1/jobs/job_8f3k2m1x \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY"

# 3. Download output.url from the finished job
curl -o shoe-4x.jpg "https://files.photo-rescue.com/results/job_8f3k2m1x.jpg?signature=..."

Authentication

Send your key in the Authorization header as a bearer token on every request. Production keys start with pr_live_; development keys start with pr_test_.

curl https://www.photo-rescue.com/api/v1/usage \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY"

Looking after keys

• A key is shown once when you create it. We store only a keyed hash and a short prefix, so we cannot show it again; create a new key if you lose it.
• Give each key a name (for example the service that uses it), so you can tell them apart and see when each was last used.
• Revoke a key in the dashboard at any time. A revoked key stops working immediately.
• Every request is scoped to the account that owns the key. Jobs, uploads and usage of other accounts are never visible.
• Keep keys on your server. Anyone who has a key can spend your credits.

Models and credits

The task field of a job picks the model. These are the same models as the site and they use the same credit rules: one image costs 1 credit, except Upscale 8× which costs 2. GET /v1/models returns this list live, including whether each model is currently enabled for your account.

• Input limits are checked before anything is charged. An image above a model's cap is refused with 413 image_too_large_for_task.
• Supported input formats are JPEG, PNG and WebP. output_format can be auto, png, jpeg or webp.

Uploading files

If your images are not on a public HTTPS address, upload them first. Uploading is two requests: ask for a presigned URL with the file size, then send the file to it with a plain PUT with the matching Content-Length. The file goes straight to storage and does not pass through the API servers.

# Step 1: ask for an upload URL (must include file size)
curl -X POST https://www.photo-rescue.com/api/v1/uploads \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": 482113}'

# Step 2: send the file to the returned url
curl -X PUT "https://uploads.photo-rescue.com/...signed-url..." \
  -H "Content-Type: image/jpeg" \
  -H "Content-Length: 482113" \
  --data-binary @shoe.jpg

{
  "upload_id": "upl_5d9q0w2e",
  "url": "https://uploads.photo-rescue.com/...signed-url...",
  "expires_at": "2026-10-10T14:18:21Z"
}

Jobs

A job is one image processed by one model. Jobs run asynchronously: creating one returns immediately, and you read the outcome by polling or webhook.

curl -X POST https://www.photo-rescue.com/api/v1/jobs \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY" \
  -H "Idempotency-Key: order-1042-photo-1" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "upscale",
    "input": { "url": "https://example.com/photos/shoe.jpg" },
    "output_format": "auto",
    "webhook_url": "https://example.com/webhooks/photorescue",
    "metadata": { "sku": "SHOE-1042" }
  }'

{
  "id": "job_8f3k2m1x",
  "object": "job",
  "status": "queued",
  "task": "upscale",
  "credits": 1,
  "created_at": "2026-10-10T14:03:21Z",
  "completed_at": null,
  "input": { "width": 1024, "height": 683 },
  "output": null,
  "error": null,
  "metadata": { "sku": "SHOE-1042" },
  "progress": { "stage": "starting", "fraction": 0, "eta_ms": null },
  "batch_id": null,
  "batch_index": null
}

curl https://www.photo-rescue.com/api/v1/jobs/job_8f3k2m1x \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY"

{
  "id": "job_8f3k2m1x",
  "object": "job",
  "status": "succeeded",
  "task": "upscale",
  "credits": 1,
  "created_at": "2026-10-10T14:03:21Z",
  "completed_at": "2026-10-10T14:03:40Z",
  "input": { "width": 1024, "height": 683 },
  "output": {
    "url": "https://files.photo-rescue.com/results/job_8f3k2m1x.jpg?signature=...",
    "width": 4096,
    "height": 2732,
    "format": "jpeg",
    "expires_at": "2026-10-10T15:03:40Z"
  },
  "error": null,
  "metadata": { "sku": "SHOE-1042" },
  "progress": null,
  "batch_id": null,
  "batch_index": null
}

curl "https://www.photo-rescue.com/api/v1/jobs?status=failed&limit=20" \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "job_2c7n9b4v", "object": "job", "status": "failed", "task": "enhance", "credits": 1, "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "cur_Zm9v"
}

curl -X DELETE https://www.photo-rescue.com/api/v1/jobs/job_8f3k2m1x \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY"

{
  "id": "job_8f3k2m1x",
  "object": "job",
  "status": "canceled",
  "task": "upscale",
  "credits": 1,
  "created_at": "2026-10-10T14:03:21Z",
  "completed_at": "2026-10-10T14:03:25Z",
  "input": { "width": 1024, "height": 683 },
  "output": null,
  "error": null,
  "metadata": { "sku": "SHOE-1042" },
  "progress": { "stage": "starting", "fraction": 0, "eta_ms": null },
  "batch_id": null,
  "batch_index": null
}

Batches

A batch is many images of one task sent in one request. Each item becomes a normal job (same credits, same refunds, same job object) with a shared batch_id, and the jobs are processed together, which is faster and cheaper for us to run than the same images sent one by one.

curl -X POST https://www.photo-rescue.com/api/v1/batches \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalog-2026-10-10" \
  -d '{
    "task": "upscale",
    "items": [
      { "input": { "upload_id": "upl_3hT9kLmN2pQ8rS4vW6xY1zA0" }, "metadata": { "sku": "SKU-1" } },
      { "input": { "url": "https://example.com/sku-2.jpg" }, "metadata": { "sku": "SKU-2" } }
    ],
    "webhook_url": "https://example.com/webhooks/photorescue"
  }'

{
  "id": "batch_4gh7jk2l",
  "object": "batch",
  "status": "processing",
  "task": "upscale",
  "created_at": "2026-10-10T14:03:21Z",
  "completed_at": null,
  "counts": { "total": 2, "queued": 2, "processing": 0, "succeeded": 0, "failed": 0, "canceled": 0 },
  "progress": 0,
  "metadata": { "shoot": "spring-catalog" },
  "jobs": [
    { "id": "job_b1a2t3c4", "object": "job", "status": "queued", "batch_id": "batch_4gh7jk2l", "batch_index": 0, "...": "..." },
    { "id": "job_b5d6e7f8", "object": "job", "status": "queued", "batch_id": "batch_4gh7jk2l", "batch_index": 1, "...": "..." }
  ],
  "rejected": []
}

curl https://www.photo-rescue.com/api/v1/batches/batch_4gh7jk2l \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY"

{
  "id": "batch_4gh7jk2l",
  "object": "batch",
  "status": "processing",
  "task": "upscale",
  "created_at": "2026-10-10T14:03:21Z",
  "completed_at": null,
  "counts": { "total": 2, "queued": 2, "processing": 0, "succeeded": 0, "failed": 0, "canceled": 0 },
  "progress": 0,
  "metadata": { "shoot": "spring-catalog" },
  "jobs": [
    { "id": "job_b1a2t3c4", "object": "job", "status": "queued", "batch_id": "batch_4gh7jk2l", "batch_index": 0, "...": "..." },
    { "id": "job_b5d6e7f8", "object": "job", "status": "queued", "batch_id": "batch_4gh7jk2l", "batch_index": 1, "...": "..." }
  ]
}

Usage

curl https://www.photo-rescue.com/api/v1/usage \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY"

{
  "object": "usage",
  "plan": "api_growth",
  "api_access": true,
  "period_start": "2026-10-01T00:00:00Z",
  "period_end": "2026-11-01T00:00:00Z",
  "credits_included": 8000,
  "credits_used": 1250,
  "credits_remaining": 6750,
  "overage_credits": 0
}

Webhooks

Instead of polling, pass a webhook_url when you create a job. When the job finishes, we send a POST with a JSON event to that address.

{
  "id": "evt_4b8c1d2e",
  "type": "job.succeeded",
  "data": {
    "id": "job_8f3k2m1x",
    "object": "job",
    "status": "succeeded",
    "task": "upscale",
    "credits": 1,
    "created_at": "2026-10-10T14:03:21Z",
    "completed_at": "2026-10-10T14:03:40Z",
    "input": { "width": 1024, "height": 683 },
    "output": { "url": "https://files.photo-rescue.com/results/job_8f3k2m1x.jpg?signature=...", "width": 4096, "height": 2732, "format": "jpeg", "expires_at": "2026-10-10T15:03:40Z" },
    "error": null,
    "metadata": { "sku": "SHOE-1042" }
  }
}

Verify the signature

Every request carries PhotoRescue-Event (the event type), PhotoRescue-Delivery (the event id, the same as id in the body) and a PhotoRescue-Signature header like t=1760105020,v1=5257a869.... t is a Unix timestamp and v1 is the hex HMAC-SHA256, keyed with your webhook secret, of the string t.body: the timestamp, a dot, then the raw request body. Recompute it and compare in constant time. Reject requests whose timestamp is more than a few minutes old, so a captured request cannot be replayed.

Find your webhook secret in the dashboard under Webhooks, where you can also rotate it and send a test event.

import hashlib
import hmac
import time


def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """Check the PhotoRescue-Signature header of a webhook request."""
    try:
        parts = dict(p.strip().split("=", 1) for p in header.split(","))
        timestamp, signature = parts["t"], parts["v1"]
        if abs(time.time() - int(timestamp)) > tolerance:
            return False  # too old: possible replay
    except (KeyError, ValueError):
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

A minimal receiver

import os
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["PHOTORESCUE_WEBHOOK_SECRET"]


@app.post("/webhooks/photorescue")
def photorescue_webhook():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    if not verify_signature(raw, request.headers.get("PhotoRescue-Signature", ""), SECRET):
        return "invalid signature", 400
    event = request.get_json()
    job = event["data"]
    if event["type"] == "job.succeeded":
        print("done", job["id"], job["output"]["url"])
    elif event["type"] == "job.failed":
        print("failed", job["id"], job["error"])
    return "", 204

Retries

• A delivery that does not succeed is retried up to 5 times with exponential backoff, over at most about an hour.
• Answer with a 2xx status as soon as you have stored the event; do slow work afterwards.
• Deliveries can repeat. Treat the event id (or the job id) as the key and ignore events you have already handled.
• The dashboard lists recent deliveries with their status. If an endpoint was down, you can always read the job with GET /v1/jobs/{id}.

Errors

Errors use an HTTP status that fits and one JSON shape, so you can branch on error.code. The message is for people, details carries structured data when there is any.

{
  "error": {
    "code": "insufficient_credits",
    "message": "This job needs 2 credits and your plan has 1 left.",
    "details": { "needed": 2, "remaining": 1 }
  }
}

• Credits are never charged for a request that returns an error before the job is accepted.
• A job that fails after it was accepted is refunded automatically and reported as job.failed.
• New error codes may be added. Treat an unknown code as its HTTP status class: retry 5xx with backoff, do not retry 4xx unchanged.

Rate limits

Limits apply per API key, and there is also a cap on how many jobs your account can have running at the same time. They depend on your plan.

When you go over, the API answers 429 rate_limited. Every response carries RateLimit-Limit and RateLimit-Remaining, and a 429 also has Retry-After: the number of seconds to wait before trying again.

import time
import requests


def request_with_retry(method, url, retries=5, **kwargs):
    for attempt in range(retries):
        r = requests.request(method, url, **kwargs)
        if r.status_code != 429:
            return r
        time.sleep(int(r.headers.get("Retry-After", 2 ** attempt)))
    return r

Jobs beyond your concurrency cap are not lost: spread them out, or use a webhook and send the next job when one finishes.

Idempotency

Networks fail. If a POST /v1/jobs times out, you cannot tell whether the job was created, and a blind retry could charge twice. Send an Idempotency-Key header with a value that is unique per logical request (an order and photo id works well).

• The same key with the same body within 24 hours returns the job that was already created, with no second charge.
• Use a new key for every new image. Reusing a key with a different body is a mistake in your code.
• Keys are scoped to your account, so they cannot clash with other customers' keys.

curl -X POST https://www.photo-rescue.com/api/v1/jobs \
  -H "Authorization: Bearer $PHOTORESCUE_API_KEY" \
  -H "Idempotency-Key: order-1042-photo-1" \
  -H "Content-Type: application/json" \
  -d '{"task":"enhance","input":{"url":"https://example.com/photos/room.jpg"}}'

Data retention

Your images are not kept. Uploaded files and results are deleted automatically after 24 hours, as the privacy policy says.

• Download results soon after the job succeeds. After 24 hours the file is gone and cannot be recovered.
• output.url is a signed link that expires in one hour. While the file still exists, GET /v1/jobs/{id} returns a fresh link.
• We do not use your images to train, fine-tune or evaluate AI models. See the Business & API Terms and the Data Processing Agreement.
• Job records (id, model, time, status and credits, with no image data) are kept longer than the images. The DPA gives the period.

Changelog

Changes that break existing integrations will ship under a new version path. New fields and new error codes can appear in v1, so ignore fields you do not know.