API reference

Authentication

All requests require a bearer token. Include the API key returned by /api-keys in the Authorization header:

Authorization: Bearer pak_live_…

Rate limits

60 requests / minute per key. Exceeding it returns 429 with a Retry-After header. Each successful job also deducts 1 credit.

POST /api/v1/images

Submits a new product photo for processing.

Request

POST https://palmou.com/api/v1/images
Authorization: Bearer pak_live_…
Content-Type: application/json

{
  "image_url": "https://your-cdn.com/product.jpg",
  "scenario_id": "premium_beige"
}

image_url (required): publicly reachable URL to a JPG, PNG, or WebP up to 10MB.
scenario_id (optional): one of studio_white, premium_beige, outdoor_nature, luxury_marble, urban_concrete, gradient_color. If omitted, the pipeline only removes the background.

Response

202 Accepted
{
  "id": "8f1c…",
  "status": "processing",
  "status_url": "https://palmou.com/api/v1/images/8f1c…"
}

GET /api/v1/images/:id

Polls a job. Status transitions: pending → removing_bg / generating_scene → upscaling → completed (or failed).

200 OK
{
  "id": "8f1c…",
  "status": "completed",
  "scenario_id": "premium_beige",
  "original_url": "https://palmou.com/storage/…/original.webp",
  "output_url": "https://palmou.com/storage/…/processed.webp",
  "error": null,
  "created_at": "2026-05-02T09:13:42Z",
  "completed_at": "2026-05-02T09:14:35Z"
}

Errors

{ "error": "INSUFFICIENT_CREDITS", "message": "...", "available": 0 }

Standard codes: MISSING_API_KEY, INVALID_API_KEY, PLAN_NOT_ALLOWED, RATE_LIMITED, VALIDATION_ERROR, FETCH_FAILED, FILE_TOO_LARGE, INVALID_FORMAT, INVALID_DIMENSIONS, INSUFFICIENT_CREDITS, REPLICATE_UNAVAILABLE, NOT_FOUND.

Polling cadence

Most jobs finish in 30–90 seconds. We recommend polling no faster than every 3 seconds. A websocket / webhook-back option is on the roadmap.