Quick Start

Base URL: https://app.uselamina.ai Auth: x-api-key: lma_your_api_key Lamina is an agentic creative API for generating videos, movies, images, and audio. High-level briefs use one plan → approve → execute lifecycle; direct app APIs remain available when you already know exactly what to run.

Path 1: Frozen plan lifecycle (recommended for agents)

1. Plan from a brief

curl -X POST \
  -H "x-api-key: lma_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"brief":"Product hero shot of white sneakers on marble","modality":"image"}' \
  https://app.uselamina.ai/v1/content/plan

Read data.canonicalStatus and data.plan:

needs_clarification / needs_input: collect questions and plan again with answers in inputs.
awaiting_choice: present alternatives, then call POST /v1/content/plans/{planId}/choose.
awaiting_approval: show the steps, warnings, estimated cost, and ask for approval.

2. Execute the exact frozen plan

curl -X POST \
  -H "x-api-key: lma_your_api_key" \
  -H "Idempotency-Key: launch-image-001" \
  -H "Content-Type: application/json" \
  -d '{"planFingerprint":"<fingerprint>","inputs":{},"maxCredits":20}' \
  https://app.uselamina.ai/v1/content/plans/<plan-id>/execute

The fingerprint prevents a changed plan from being executed after approval. maxCredits is a hard ceiling. If cost is unknown, execution also requires allowUnknownCost: true.

3. Read durable status

curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/content/runs/<run-id>

The snapshot contains progress, per-step state, final outputs, cancellation state, and typed errors. For a trusted unattended worker, POST /v1/content/create with headless: true provides a compatibility shortcut, but still requires Idempotency-Key, maxCredits, and an approval-ready plan. It never bypasses clarification or route choice.

Path 2: Full control (choose the app yourself)

When you need to pick a specific app, inspect its parameters, and provide exact inputs.

1. Discover an app

curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/apps

import requests

API_KEY = "lma_your_key"
BASE = "https://app.uselamina.ai/v1"
H = {"x-api-key": API_KEY, "Content-Type": "application/json"}

apps = requests.get(f"{BASE}/apps", headers=H).json()["data"]

const API_KEY = 'lma_your_key';
const BASE = 'https://app.uselamina.ai/v1';
const headers = { 'x-api-key': API_KEY, 'Content-Type': 'application/json' };

const apps = await fetch(`${BASE}/apps`, { headers }).then(r => r.json());

Use search when you know the capability you want to build around:

curl -H "x-api-key: lma_your_api_key" \
  "https://app.uselamina.ai/v1/apps?search=catalog"

apps = requests.get(f"{BASE}/apps?search=catalog", headers=H).json()["data"]
app_id = apps[0]["appId"]

const searchRes = await fetch(`${BASE}/apps?search=catalog`, { headers }).then(r => r.json());
const appId = searchRes.data[0].appId;

Pick an appId from the response.

2. Inspect the input schema

curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/apps/{appId}

app = requests.get(f"{BASE}/apps/{app_id}", headers=H).json()["data"]
print(app["parameters"])  # shows what inputs to provide

const app = await fetch(`${BASE}/apps/${appId}`, { headers }).then(r => r.json());
console.log(app.data.parameters);  // shows what inputs to provide

{
  "data": {
    "appId": "{appId}",
    "name": "Example Catalog App",
    "description": "Generate catalog images from product inputs",
    "parameters": [
      {
        "id": "front-image",
        "name": "Front",
        "type": "url",
        "required": true,
        "accept": ["image"]
      },
      {
        "id": "location",
        "name": "Location",
        "type": "options",
        "required": true,
        "options": ["Studio", "Urban", "Park"],
        "default": "Studio"
      },
      {
        "id": "prompt",
        "name": "Prompt",
        "type": "text",
        "required": true
      }
    ]
  }
}

Use the parameter name as the key when sending inputs. For options, send the label from the options array. This lets your backend or UI adapt to different apps without changing the execution contract.

3. Start execution

curl -X POST \
  -H "x-api-key: lma_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "Front": "https://example.com/front.jpg",
      "Location": "Studio"
    }
  }' \
  "https://app.uselamina.ai/v1/apps/{appId}/runs?webhook=https://your-server.com/callback"

r = requests.post(f"{BASE}/apps/{app_id}/runs?webhook=https://your-server.com/cb",
    headers=H, json={"inputs": {"Front": "https://example.com/front.jpg", "Location": "Studio"}})
exec_id = r.json()["data"]["runId"]

const res = await fetch(`${BASE}/apps/${appId}/runs?webhook=${encodeURIComponent('https://your-server.com/callback')}`, {
  method: 'POST', headers,
  body: JSON.stringify({ inputs: { "Front": "https://example.com/front.jpg", "Location": "Studio" } }),
});
const { data } = await res.json();
const execId = data.runId;

For local testing or simpler integrations, you can omit ?webhook= and poll or wait instead.

{
  "data": {
    "runId": "<execution-id>",
    "workflowId": "{appId}",
    "workflowName": "Example Catalog App",
    "status": "queued",
    "outputs": [
      {
        "id": "node-1",
        "label": "Catalog Output",
        "type": "pending",
        "value": null,
        "status": "pending",
        "error": null
      }
    ]
  }
}

4. Get results

Three options depending on your integration: Via wait (simplest for agents): Block until the execution finishes or the timeout expires. No polling loop needed.

curl -H "x-api-key: lma_your_api_key" \
  "https://app.uselamina.ai/v1/runs/<execution-id>/wait?timeout=60"

result = requests.get(f"{BASE}/runs/{exec_id}/wait?timeout=60", headers=H).json()
for o in result["data"]["outputs"]:
    print(f"{o['label']}: {o['value']}")

const result = await fetch(
  `${BASE}/runs/${execId}/wait?timeout=60`, { headers }
).then(r => r.json());

for (const output of result.data.outputs) {
  console.log(`${output.label}: ${output.value}`);
}

Use timeout=60 for image workflows, timeout=120 for video. If it times out, timeout: true is returned alongside the current state — call again or fall back to polling. Via webhook: If you passed ?webhook=, your callback URL receives a POST with the results when the execution completes. The payload has the same structure as the polling response below, signed with ED25519 headers for verification. Via polling: Poll every 3-5 seconds:

curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/runs/<execution-id>

import time

while True:
    status = requests.get(f"{BASE}/runs/{exec_id}", headers=H).json()["data"]
    if status["status"] in ("completed", "failed"):
        for o in status["outputs"]:
            print(f"{o['label']}: {o['value']}")
        break
    time.sleep(5)

const poll = async (execId) => {
  while (true) {
    const r = await fetch(`${BASE}/runs/${execId}`, { headers });
    const { data } = await r.json();
    if (data.status === 'completed' || data.status === 'failed') return data;
    await new Promise((r) => setTimeout(r, 5000));
  }
};

const finalResult = await poll(execId);

Status flow: queued -> running -> completed or failed When status is "completed", output type changes from "pending" to "image", "video", or "text", and value contains the result:

{
  "data": {
    "runId": "<execution-id>",
    "status": "completed",
    "outputs": [
      {
        "id": "node-1",
        "label": "AI Designer",
        "type": "image",
        "value": "https://storage.example.com/generated/catalog-image.png",
        "status": "completed",
        "error": null
      }
    ],
    "errorMessage": null,
    "startedAt": "2026-03-23T12:22:41.694Z",
    "completedAt": "2026-03-23T12:24:15.000Z",
    "createdAt": "2026-03-23T12:22:40.552Z"
  }
}

If status is "failed", check errorMessage and each output’s error field.

Score and distribute (optional)

After creation, you can:

Score content: POST /v1/content/score — evaluate quality against brand context before publishing
Publish: POST /v1/publishing/publish — send to connected social channels
Transfer to CDN: POST /v1/publishing/transfer-asset — permanent hosting on your own infrastructure

What’s next

Key Concepts — understand the Creative Engine mental model
Agent Integration Patterns
Integration Recipes
Use the CLI and SDK

Overview

Install

Concepts

API Reference

Guides

Path 1: Frozen plan lifecycle (recommended for agents)

1. Plan from a brief

2. Execute the exact frozen plan

3. Read durable status

Path 2: Full control (choose the app yourself)

1. Discover an app

2. Inspect the input schema

3. Start execution

4. Get results

Score and distribute (optional)

What’s next

​Path 1: Frozen plan lifecycle (recommended for agents)

​1. Plan from a brief

​2. Execute the exact frozen plan

​3. Read durable status

​Path 2: Full control (choose the app yourself)

​1. Discover an app

​2. Inspect the input schema

​3. Start execution

​4. Get results

​Score and distribute (optional)

​What’s next

Path 1: Frozen plan lifecycle (recommended for agents)

1. Plan from a brief

2. Execute the exact frozen plan

3. Read durable status

Path 2: Full control (choose the app yourself)

1. Discover an app

2. Inspect the input schema

3. Start execution

4. Get results

Score and distribute (optional)

What’s next