> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselamina.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Recipes

> Map common generative media use cases to the real Lamina `/v1` API for image, catalog, try-on, and video workflows.

Use this guide when you want to turn Lamina into a product feature, not just call a raw model.

Each recipe below uses the same execution pattern:

1. discover the right app
2. inspect its schema
3. start an execution
4. receive results by webhook or polling

That makes the API predictable for application developers even when the underlying workflow changes.

## The Real API Behind Every Recipe

The `/v1` API has 24 endpoints across 9 groups. The core execution flow uses:

* `GET /v1/apps` — discover apps
* `GET /v1/apps/{appId}` — inspect inputs
* `POST /v1/apps/{appId}/runs` — run
* `GET /v1/runs/{runId}` — poll results

Additional groups — Intelligence, Publishing, Content, Templates, Assets, Account — extend what you can do after execution. See the full [API Reference](/api-reference/list-apps).

## Core Contract

| Capability need                               | Current executable Lamina endpoint   |
| --------------------------------------------- | ------------------------------------ |
| Start image, catalog, try-on, or video work   | `POST /v1/apps/{appId}/runs`         |
| Check job status                              | `GET /v1/runs/{runId}`               |
| Stream job progress in real time              | `GET /v1/runs/{runId}/stream`        |
| Discover which app to call                    | `GET /v1/apps`                       |
| Verify the exact input schema                 | `GET /v1/apps/{appId}`               |
| Intelligent content creation (agent-friendly) | `POST /v1/content/create`            |
| Batch multiple creations                      | `POST /v1/content/batch`             |
| Get brand context for grounded prompts        | `GET /v1/intelligence/brand-context` |
| Publish to social channels                    | `POST /v1/publishing/publish`        |
| Check credit balance                          | `GET /v1/account/usage`              |

### Authentication

```http theme={null}
x-api-key: lma_your_api_key
Authorization: Bearer lma_your_api_key
```

### Rate Limits

All `/v1/*` endpoints are currently limited to **100 requests per minute per IP**.

On `429 Too Many Requests`, read these headers before retrying:

* `RateLimit-Limit`
* `RateLimit-Remaining`
* `RateLimit-Reset`
* `Retry-After`

### Common Status Codes

| Status | Meaning                                      |
| ------ | -------------------------------------------- |
| `200`  | Successful read                              |
| `202`  | Execution accepted and queued                |
| `400`  | Invalid request body, webhook URL, or inputs |
| `401`  | Missing or invalid API key                   |
| `403`  | Workspace or app access denied               |
| `404`  | App or execution not found                   |
| `429`  | Rate limit exceeded                          |
| `500`  | Unexpected server-side failure               |

## Example Public Apps By Capability

These are example public apps observed on **April 11, 2026**. Use them as capability anchors in docs or demos, but pin the exact `appId` you want to support in production and re-check its schema with `GET /v1/apps/{appId}` before you ship against it.

| Capability               | Example public app                        | Example appId                          |
| ------------------------ | ----------------------------------------- | -------------------------------------- |
| Single image generation  | `Product Shots with Mood Board`           | `ec7ec3ce-69b4-43c9-8eea-fe9752d679a4` |
| Batch catalog generation | `Premium Catalog 1.0`                     | `bbb17293-5fe7-4645-8c6e-0745bc28254d` |
| Batch catalog generation | `Swift Catalog Generation`                | `de5cca6b-73aa-4e27-a714-3339024db15d` |
| Virtual try-on           | `Product Try on`                          | `a76e85ec-20b4-4fbc-99ad-055423a868a2` |
| Video generation         | `Eyewear Shoot (Multi-Shot 21s Video)`    | `1afc70fd-cb66-4f44-847d-bdaf7e237be4` |
| Video generation         | `Performance Marketing Video (V3) Sample` | `ec9b3525-4b72-4083-a6cb-00371672e128` |

## Ecommerce Image Generation

Use this pattern for:

* product shots
* background swaps
* lifestyle scenes
* hero images

**Recommended backing app example:** `Product Shots with Mood Board`

### Typical integration flow

```bash theme={null}
curl -H "Authorization: Bearer $LAMINA_API_KEY" \
  "https://app.uselamina.ai/v1/apps?search=product"
```

Then inspect the chosen app and use the returned parameter names exactly:

```bash theme={null}
curl -H "Authorization: Bearer $LAMINA_API_KEY" \
  https://app.uselamina.ai/v1/apps/<appId>
```

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $LAMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "<parameter name from GET /v1/apps/{appId}>": "<value>"
    }
  }' \
  https://app.uselamina.ai/v1/apps/<appId>/runs
```

### What developers usually send

* a product image URL or a set of source images
* optional reference imagery
* a prompt or creative brief
* styling or environment choices exposed as `options`

### What to expect back

* one or more generated image outputs
* occasional text outputs for summaries or metadata
* `queued` or `running` before final media is ready

## Catalog And Merchandising Automation

Catalog workflows are usually run by commerce backends, merchant tooling, or creative ops teams that need consistent outputs across many products.

**Recommended backing app examples:**

* `Premium Catalog 1.0`
* `Swift Catalog Generation`

For a concrete catalog payload, the existing Quick Start example uses:

* front image URL
* back image URL
* model or style options such as gender, ethnicity, body type, and location

Example execution body:

```json theme={null}
{
  "inputs": {
    "Front": "https://example.com/front.jpg",
    "Back": "https://example.com/back.jpg",
    "Model Gender": "Female",
    "Location": "Studio"
  }
}
```

Send it to:

```http theme={null}
POST /v1/apps/{catalogAppId}/runs
```

### Good fit for

* marketplace seller onboarding
* catalog enrichment pipelines
* merchandising teams refreshing seasonal collections
* internal creative production systems

## Virtual Try-On

Try-on integrations usually combine shopper-uploaded imagery, mannequin imagery, or model imagery with garment assets supplied by a commerce system.

**Recommended backing app example:** `Product Try on`

Suggested discovery query:

```bash theme={null}
curl -H "Authorization: Bearer $LAMINA_API_KEY" \
  "https://app.uselamina.ai/v1/apps?search=try on"
```

Expected input pattern:

* one or more person or selfie image URLs
* one or more garment image URLs
* optional fit, pose, or styling fields depending on the app

Execution call:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $LAMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "<selfie parameter>": "https://example.com/person.jpg",
      "<garment parameter>": "https://example.com/garment.jpg"
    }
  }' \
  https://app.uselamina.ai/v1/apps/<tryOnAppId>/runs
```

### Common platform pattern

* fetch the app schema at startup or cache it server-side
* render the form dynamically for internal tooling or merchant portals
* pass the resulting execution ID into your job UI
* use webhooks for completion updates instead of aggressive polling

## Video Generation

Video generation follows the same app-execution pattern, but jobs are more likely to be long-running and media-heavy. This is a good fit for product marketing tools, seller studios, and content platforms generating motion assets from still inputs.

**Recommended backing app examples:**

* `Eyewear Shoot (Multi-Shot 21s Video)`
* `Performance Marketing Video (V3) Sample`

Suggested discovery query:

```bash theme={null}
curl -H "Authorization: Bearer $LAMINA_API_KEY" \
  "https://app.uselamina.ai/v1/apps?search=video"
```

Common input pattern:

* one or more source image URLs
* optional product or motion brief text
* optional aspect ratio, duration, or style fields from app metadata

Execution call:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $LAMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "<image parameter>": "https://example.com/product.jpg",
      "<prompt parameter>": "Create a premium ecommerce product reel"
    }
  }' \
  "https://app.uselamina.ai/v1/apps/<videoAppId>/runs?webhook=https://your-server.com/callback"
```

Use webhooks in production for video jobs. They are often long-running enough that polling is only a fallback.

## Job Status And Result Retrieval

Every capability above resolves to the same status check:

```http theme={null}
GET /v1/runs/{runId}
```

Use the run ID returned from `POST /v1/apps/{appId}/runs`. Poll every 3-5 seconds until the run reaches `completed` or `failed`.

If you are using webhooks, verify the callback signature with:

```http theme={null}
GET /v1/webhooks/signing-key
```

## Production Guidelines

If you are building a customer-facing integration or partner API on top of Lamina:

1. pin the `appId` values you support instead of relying on search at runtime
2. re-fetch app metadata when you deploy changes to a workflow or form
3. validate inputs against the latest parameter schema before execution
4. prefer webhooks for long-running image and video jobs
5. design your UI around execution states, not immediate outputs

The underlying API stays small on purpose. Most of the product-specific behavior lives in the apps you choose to expose.