Public API overview

What Katalo does

Katalo is an AI virtual staging platform for real-estate imagery. It turns empty, dated, or unfinished property photos into photorealistic, listing-ready images so agents, brokerages, portals, and real-estate software teams can market properties without physical staging or manual Photoshop production. The API lets your backend submit one source image, choose the workflow and style, wait for completion, and read back one primary output plus an optional approved alternate.

Virtual staging

Furnish empty or under-presented rooms with realistic listing visuals.

Property-ready outputs

Return approved images your system can publish, store, or review.

Backend integration

Embed staging into CRMs, portals, listing pipelines, and batch workers.

Integrate Katalo from your backend

This documentation is for backend and platform engineers. The public API is server-to-server only: your backend owns the API key, ingests source assets, creates jobs, receives results by webhook or polling, and decides whether to persist signed output assets.

One input

Each job is tied to one original source image.

Async jobs

Create returns a job immediately, then the job moves through terminal state.

Two delivery modes

Consume a signed webhook or poll the read endpoint.

When this API fits

Integration pattern	Why it fits
CRM and brokerage software	Create or regenerate listing imagery without sending agents into the Katalo UI.
Marketplace and portal backends	Attach generation jobs to listing ingestion, moderation, or merchandising flows.
Batch and queue workers	Create jobs from your own workers and fan results back into storage, search, or product UI.
White-label product features	Expose staging to your users while keeping credentials, policy, and delivery logic on your backend.
Internal reporting	Read usage summaries and billing ledger entries for reconciliation and support tooling.

Request flow

Ingest the source image with POST /api/v1/source-assets.
Poll GET /api/v1/source-assets/{ingest_id} until source_asset_id is ready.
Create a generation with POST /api/v1/generations.
Wait for succeeded or failed using a webhook or GET /api/v1/generations/{job_id}.
Consume signed output URLs immediately, or copy assets into your own storage for durable access.
Regenerate with POST /api/v1/generations/{job_id}/regenerate when you need another approved output from the same source.

Inline file and source_url submission on POST /api/v1/generations still works as a compatibility path, but the production contract should create a reusable source asset first.

Contract rules

A job always uses one original image.
Public responses include only publishable outputs: the primary approved output and, if requested, at most one approved alternate.
Signed output URLs are temporary. Copy images into your own storage if they need to remain available.
Request validity depends on workflow and capture_type; some fields are required, optional, or explicitly not allowed.

Your integration owns

Responsibility	Guidance
Authentication	Store the organization API key on the server and send it as a bearer token.
Completion	Use signed webhooks in production and keep polling available for recovery.
Correlation	Use `reference`, `metadata`, and your own internal ids to map completion back to listings.
Asset persistence	Copy signed output assets into your own bucket when you need durable access.
Retry policy	Use idempotency keys on writes and retry only retryable failures.
Usage reconciliation	Use usage and billing endpoints for reporting, support, and chargeback.

Quickstart

curl https://app.katalo.ai/api/v1/source-assets \
  -X POST \
  -H "Authorization: Bearer $KATALO_API_KEY" \
  -H "Idempotency-Key: source-listing-123-lr-1" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/listings/empty-living-room.jpg"
  }'

curl https://app.katalo.ai/api/v1/generations \
  -X POST \
  -H "Authorization: Bearer $KATALO_API_KEY" \
  -H "Idempotency-Key: generation-listing-123-lr-1" \
  -H "Content-Type: application/json" \
  -d '{
    "source_asset_id": "src_01JXSRCABCDEFGHIJKL012345",
    "workflow": "staging",
    "capture_type": "photo",
    "mode": "refurnish",
    "room_types": ["Living Room", "Kitchen"],
    "style_preset": "modern",
    "include_alternates": true,
    "reference": "listing-123-lr-1",
    "metadata": {
      "listing_id": "listing-123",
      "partner": "acme"
    },
    "webhook": {
      "url": "https://partner.example.com/webhooks/katalo"
    }
  }'

Continue reading

API keys

Create, store, rotate, and revoke credentials.

Generations

Read the create, get, and regenerate contracts.

Webhooks

Verify signatures and consume completion events.

OpenAPI

Use the machine-readable API contract.

Getting Started

API

Operations

Reference

What Katalo does

Virtual staging

Property-ready outputs

Backend integration

Integrate Katalo from your backend

One input

Async jobs

Two delivery modes

When this API fits

Request flow

Contract rules

Your integration owns

Quickstart

Continue reading

API keys

Generations

Webhooks

OpenAPI

​What Katalo does

Virtual staging

Property-ready outputs

Backend integration

​Integrate Katalo from your backend

One input

Async jobs

Two delivery modes

​When this API fits

​Request flow

​Contract rules

​Your integration owns

​Quickstart

​Continue reading

API keys

Generations

Webhooks

OpenAPI

What Katalo does

Integrate Katalo from your backend

When this API fits

Request flow

Contract rules

Your integration owns

Quickstart

Continue reading