---
title: "Submit an image-editing job"
method: POST
path: "/api/process"
---

# Submit an image-editing job

`POST /api/process`

## Request

- Base URL: `https://api.peelaway.io`
- URL: `https://api.peelaway.io/api/process`
- Auth: HTTP bearer

Submit one image (or a batch of up to 50) with a natural-language prompt. Returns a job_id immediately; processing runs asynchronously. Supports the standard `Idempotency-Key` header so retries don't double-charge.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - SingleProcessRequest
    - `image` string, required: Base64-encoded image bytes (JPEG, PNG, or WebP).
    - `prompt` string, required: Natural-language edit instruction. Use 'remove X' for object removal, 'remove the background' for background removal, anything else for generative editing.
    - `negative_prompt` string
    - `format` 'jpeg' | 'png' | 'webp': Output format. Background removal always returns PNG to preserve transparency; other workflows default to JPEG.
    - `quality` integer: Output quality for lossy formats.
    - `webhook_url` string, uri: Optional public https URL. Peelaway POSTs a signed callback here when the job settles (done or error), with retry backoff. The body carries job_id, status, the metadata block, and result_url (on done) or a generic error (on error). Verify X-Peelaway-Signature (sha256=HMAC over `${X-Peelaway-Timestamp}.${rawBody}`) with the secret from GET /api/webhooks/secret, and dedupe retries on job_id.
  - BatchProcessRequest
    - `images` SingleProcessRequest[], required
      - `image` string, required: Base64-encoded image bytes (JPEG, PNG, or WebP).
      - `prompt` string, required: Natural-language edit instruction. Use 'remove X' for object removal, 'remove the background' for background removal, anything else for generative editing.
      - `negative_prompt` string
      - `format` 'jpeg' | 'png' | 'webp': Output format. Background removal always returns PNG to preserve transparency; other workflows default to JPEG.
      - `quality` integer: Output quality for lossy formats.
      - `webhook_url` string, uri: Optional public https URL. Peelaway POSTs a signed callback here when the job settles (done or error), with retry backoff. The body carries job_id, status, the metadata block, and result_url (on done) or a generic error (on error). Verify X-Peelaway-Signature (sha256=HMAC over `${X-Peelaway-Timestamp}.${rawBody}`) with the secret from GET /api/webhooks/secret, and dedupe retries on job_id.

## Response `200`

Job(s) accepted for processing

- union
  - object
    - `job_id` string, required
    - `credits_remaining` integer, required
  - object
    - `batch_id` string, required
    - `jobs` object[], required
      - `job_id` string
      - `status` 'pending' | 'error'
      - `error` string
    - `credits_remaining` integer, required

## Other responses

- `400`: Invalid request (code: batch_exceeds_plan_limit when a batch is larger than the plan's concurrency limit)
- `402`: Insufficient credits
- `403`: Web-only feature or public visibility permission required
- `429`: Throttled — code: rate_limited (honor Retry-After) or too_many_in_flight. Limits scale with plan.
- `502`: Upstream provider failure

---

[API](https://skmtc.dev/peelaway/apis/peelaway-image-api.md) · [All operations](https://skmtc.dev/peelaway/apis/peelaway-image-api/llms.txt) · [OpenAPI document](https://skmtc.dev/peelaway/apis/peelaway-image-api/revisions/8ce45533c9d0?raw)