Documentation Index
Fetch the complete documentation index at: https://docs.katalo.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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}
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
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 |
Style presets
The public API accepts canonical preset ids: modern, scandi, boho, country, industrial, mediterranean, luxury, eclectic, and japandia.
