Generations

The recommended flow is two-step ingest: create a reusable source asset, poll until it is ready, then create a generation from source_asset_id.

Source assets

Endpoint	Purpose
`POST /api/v1/source-assets`	Submit one original image as multipart upload or `source_url` and reserve an ingest job.
`GET /api/v1/source-assets/{ingest_id}`	Poll until the ingest job reaches `ready` and returns `source_asset_id`.
`POST /api/v1/generations`	Create a generation job from the ready `source_asset_id`.

Inline file and source_url create requests are still accepted on POST /api/v1/generations, but they are compatibility mode. They can return status=ingesting until deferred source ingest finishes.

Lifecycle

Step	Endpoint or mechanism	What it does
1. Ingest	`POST /api/v1/source-assets`	Creates a source ingest job and eventually yields a reusable `source_asset_id`.
2. Create	`POST /api/v1/generations`	Starts a new generation job from `source_asset_id` and returns the public `job_id` immediately.
3. Complete	Webhook or `GET /api/v1/generations/{job_id}`	Wait until the job reaches `succeeded` or `failed`.
4. Recover	`GET /api/v1/generations/{job_id}`	Re-read final state if webhook delivery failed or a signed output URL expired.
5. Iterate	`POST /api/v1/generations/{job_id}/regenerate`	Create a new job from the same source asset.

Create a generation

POST /api/v1/generations

Create a job from one source image. Use the returned job_id to poll status or correlate webhook delivery.

Exactly one of file, source_url, or source_asset_id is allowed in a single request.

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"
    }
  }'

Create request fields

Field	Location	Necessity	Notes
`Authorization`	header	required	Organization-scoped API key in `Bearer <token>` format.
`Idempotency-Key`	header	required	Reusing the same key with the same payload returns the original job.
`file`	multipart	conditional	Upload one source image directly. Mutually exclusive with `source_url` and `source_asset_id`.
`source_url`	body	conditional	HTTPS URL Katalo can fetch as the original image.
`source_asset_id`	body	conditional	Existing Katalo source asset id to reuse as the input image.
`workflow`	body	required	`staging` or `pro_capture`.
`capture_type`	body	required	`photo`, `panorama360`, or `floorplan`.
`mode`	body	conditional	Required for `staging + photo`, including `clean`. Not allowed for `pro_capture`, `panorama360`, or `floorplan`.
`room_types`	body	conditional	Required for staged photo jobs unless `mode=clean`. Must stay within one supported room family.
`style_preset`	body	conditional	Required for staged panoramas. Optional for staged photos except `mode=clean`.
`include_alternates`	body	optional	Returns the primary approved output plus at most one approved alternate.
`reference`	body	optional	Your stable identifier for the source image or listing context.
`metadata`	body	optional	Up to 20 key-value properties echoed back in responses and webhooks.
`webhook.url`	body	optional	Per-request callback URL override. The signing secret is organization-level.

Get a generation

GET /api/v1/generations/{job_id}

Read job state by public id. Use this endpoint for polling, recovery, or fresh signed output URLs.

curl https://app.katalo.ai/api/v1/generations/job_01JXJOBABCDEFGHIJKL0123456 \
  -H "Authorization: Bearer $KATALO_API_KEY"

image_url values are signed and short-lived. Persist the asset in your own storage if your workflow needs longer retention.

Regenerate a generation

POST /api/v1/generations/{job_id}/regenerate

Create a new job from the same source asset as a previous job. Allowed overrides depend on the parent job’s workflow and capture type.

curl https://app.katalo.ai/api/v1/generations/job_01JXJOBABCDEFGHIJKL0123456/regenerate \
  -X POST \
  -H "Authorization: Bearer $KATALO_API_KEY" \
  -H "Idempotency-Key: regenerate-listing-123-lr-2" \
  -H "Content-Type: application/json" \
  -d '{
    "include_alternates": true,
    "reference": "listing-123-lr-2",
    "metadata": {
      "listing_id": "listing-123",
      "attempt": 2
    }
  }'

Response model

Create, get, and regenerate return the same job envelope.

Field	Meaning
`job_id`	Public id for the job.
`parent_job_id`	Parent job id when created via regenerate.
`source_asset_id`	Public source asset id tied to the original input image.
`status`	`ingesting`, `queued`, `running`, `succeeded`, or `failed`.
`workflow`	Stored workflow in public API form.
`capture_type`	Stored capture type in public API form.
`mode`	Returned mode, or `null` when the workflow does not use one.
`room_types`	Canonical room labels stored for the job. Empty for clean jobs.
`style_preset`	Canonical style preset, or `null` for clean jobs.
`include_alternates`	Whether the response can include one approved alternate output.
`reference`	Your original identifier echoed back unchanged.
`metadata`	Your original metadata echoed back unchanged.
`failure`	Terminal failure details with `code`, `message`, and `retryable`.
`outputs`	Primary approved output first, plus at most one approved alternate.
`created_at`	Job creation timestamp.
`completed_at`	Completion timestamp when the job reaches a terminal state.
`updated_at`	Last job update timestamp.

Shared workflow model

Field	Values
`workflow`	`staging`, `pro_capture`
`capture_type`	`photo`, `panorama360`, `floorplan`
`mode`	Only valid for `staging + photo`; panorama and floorplan derive mode from `capture_type`.

Room family rules

Multi-room staging requests must stay inside one supported family.

Family	Values
Single room	Any canonical room value is valid on its own.
Open plan	`Living Room`, `Kitchen`, `Dining Room`
Wet rooms	`Bathroom`, `Shower`, `Toilet`
Studio	`Bedroom` plus one or more of `Living Room`, `Kitchen`, `Dining Room`

Style presets

The public API accepts canonical preset ids: modern, scandi, boho, country, industrial, mediterranean, luxury, eclectic, and japandia.

Getting Started

API

Operations

Reference

Source assets

Lifecycle

Create a generation

Create request fields

Get a generation

Regenerate a generation

Response model

Shared workflow model

Room family rules

Style presets

​Source assets

​Lifecycle

​Create a generation

​Create request fields

​Get a generation

​Regenerate a generation

​Response model

​Shared workflow model

​Room family rules

​Style presets

Source assets

Lifecycle

Create a generation

Create request fields

Get a generation

Regenerate a generation

Response model

Shared workflow model

Room family rules

Style presets