API
Generations
Create jobs, read job state, and regenerate from the same source asset using the app’s workflow model.
Input
Source assets are the primary create input
Use the source-asset endpoints first, then create or regenerate generations from the resulting `source_asset_id`.
| 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`. |
Compatibility behavior
Inline `file` and `source_url` create requests are still accepted on POST /generations, but they are documented as compatibility mode. Expect `status=ingesting` until the deferred source ingest finishes.
Generations reference
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`. The generations API also supports transitional inline `file` and `source_url` submission, which returns a generation in `ingesting` state until the source asset is ready.
Mode-specific request rules
Panorama requests must include style_preset. Clean photo requests still require mode=clean, but they do not require room_types or style_preset.
Lifecycle
How generations and webhooks fit together
After source ingest and generation create, choose webhook delivery or polling. `GET /generations/{job_id}` remains the fallback source of truth either way.
curl https://app.katalo.ai/api/v1/source-assets \
-H "Authorization: Bearer $KATALO_API_KEY" \
-H "Idempotency-Key: listing-123-source-001" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://cdn.example.com/listings/empty-living-room.jpg"
}'
# poll GET /api/v1/source-assets/{ingest_id} until source_asset_id is present
curl https://app.katalo.ai/api/v1/generations \
-H "Authorization: Bearer $KATALO_API_KEY" \
-H "Idempotency-Key: listing-123-create-001" \
-H "Content-Type: application/json" \
-d '{
"source_asset_id": "src_...",
"workflow": "staging",
"capture_type": "photo",
"mode": "refurnish",
"room_types": ["Living Room", "Kitchen"],
"style_preset": "modern",
"reference": "listing-123-lr-1",
"webhook": {
"url": "https://partner.example.com/webhooks/katalo"
}
}'Source assets come first
In production, ingest the original image with POST /source-assets, wait until `source_asset_id` is ready, then create the generation job from that asset.
Recommended flow
After source ingest, the usual flow is POST /generations, wait for a webhook, then copy or persist the returned assets if your workflow needs durable storage.
Why GET still exists
Webhooks are a delivery mechanism, not a permanent source of truth. You still use GET /generations/{job_id} to recover from missed events, verify final state, or read fresh signed URLs after the original ones expire.
| 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} | Either wait for a signed callback or poll until the job reaches `succeeded` or `failed`. |
| 4. Recover | GET /api/v1/generations/{job_id} | Re-read final state if webhook delivery failed or if a signed output URL has expired. |
| 5. Iterate | POST /api/v1/generations/{job_id}/regenerate | Create a new job from the same source asset when you need another approved output. |
Create
POST /api/v1/generations
Create a job from one source image. Use the returned `job_id` to poll status or correlate webhook delivery.
/api/v1/generationscurl -X POST "https://app.katalo.ai/api/v1/generations" \
-H "Authorization: Bearer $KATALO_API_KEY" \
-H "Idempotency-Key: create-001" \
-H "Content-Type: application/json" \
--data '{
"source_url": "https://cdn.example.com/listings/empty-living-room.jpg",
"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"
}
}'This is the write endpoint for new jobs.
The request must include exactly one source input and only the fields that are valid for that workflow and capture type.
Input exclusivity
Exactly one of file, source_url, or source_asset_id is allowed in a single request.
Learn more
Shared workflow model
Public enum values used across create, get, and regenerate.
Learn more
Room family rules
Multi-room staging requests must stay inside one supported family.
Learn more
Canonical style preset values
The public API accepts only canonical preset ids. `style_preset` is required for `staging + panorama360`, optional for `staging + photo`, and ignored for `staging + photo + mode=clean`.
Retrieve
GET /api/v1/generations/{job_id}
Read job state by public id. Use this endpoint for polling, recovery, or to fetch fresh signed output URLs.
/api/v1/generations/{job_id}curl -X GET "https://app.katalo.ai/api/v1/generations/job_01JXJOBABCDEFGHIJKL0123456" \
-H "Authorization: Bearer $KATALO_API_KEY"Use this as the polling endpoint after create or regenerate returns a job_id.
Signed output URLs are temporary. Re-read the job if a URL has expired.
Temporary output URLs
image_url values are signed and short-lived. Persist the asset in your own storage if your workflow needs longer retention.
Regenerate
POST /api/v1/generations/{job_id}/regenerate
Create a new job from the same source asset when you need another approved output or another pass from the same original image.
/api/v1/generations/{job_id}/regeneratecurl -X POST "https://app.katalo.ai/api/v1/generations/job_01JXJOBABCDEFGHIJKL0123456/regenerate" \
-H "Authorization: Bearer $KATALO_API_KEY" \
-H "Idempotency-Key: regenerate-001" \
-H "Content-Type: application/json" \
--data '{
"mode": "renovate",
"room_types": [
"Living Room",
"Dining Room"
],
"style_preset": "mediterranean",
"reference": "listing-123-lr-redesign-2",
"metadata": {
"note": "second pass"
}
}'Regenerate always reuses the source asset from the parent job and returns a new public job_id.
Use it for retries, alternate approved outputs, or a follow-up pass from the same original image.
Override limits
Allowed override fields depend on the parent job’s workflow and capture_type.
Learn more
Shared workflow model
Public enum values used across create, get, and regenerate.
Learn more
Room family rules
Multi-room staging requests must stay inside one supported family.
Learn more
Canonical style preset values
The public API accepts only canonical preset ids. `style_preset` is required for `staging + panorama360`, optional for `staging + photo`, and ignored for `staging + photo + mode=clean`.