> ## 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.

# Generations

> Create jobs, read job state, and regenerate from the same source asset using Katalo's workflow model.

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`.                                |

<Note>
  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.
</Note>

## 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

```http theme={null}
POST /api/v1/generations
```

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

<Warning>
  Exactly one of `file`, `source_url`, or `source_asset_id` is allowed in a single request.
</Warning>

```bash theme={null}
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

```http theme={null}
GET /api/v1/generations/{job_id}
```

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

```bash theme={null}
curl https://app.katalo.ai/api/v1/generations/job_01JXJOBABCDEFGHIJKL0123456 \
  -H "Authorization: Bearer $KATALO_API_KEY"
```

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

## Regenerate a generation

```http theme={null}
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.

```bash theme={null}
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`.