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

# Create Content

> Compatibility endpoint over Lamina's canonical frozen-plan lifecycle.
Interactive calls return clarification questions, route choices, or an
approval-ready plan without dispatching generation. Unattended calls must
set `headless: true`, send `Idempotency-Key`, and provide a positive
`maxCredits`; they execute only an approval-ready plan within that ceiling.


One-call creation. Describe what you want, and the API handles app selection, input mapping, brand context injection, and execution.

Instead of manually choosing an app and mapping inputs, pass a `brief` describing the content you need. The engine resolves brand context, selects the best-fit app, injects creative guidance, and starts the execution.

The operation is asynchronous — use the returned run ID with the wait, stream, or get-run endpoints to retrieve results.

Best for agent-driven workflows where you want a single call to go from intent to finished asset.

## Headless mode (unattended agents)

By default, `create` may return `status: "needs_input"` with `askUser` prompts when the chosen path needs information a human would supply — a dead end for an unattended worker or agent.

Pass `headless: true` (or `terminalMode: "auto"`) to make the call reliable for agentic callers. In headless mode the engine:

* **forces the self-drafting recipe path** and dispatches best-effort — it **never returns `needs_input`**;
* returns `status: "unmatched"` (machine-actionable) if a run genuinely can't be formed, instead of an interactive ask;
* surfaces any unmet asks on the `ran` response as structured `unmetAsks[]` — each `{ name, key, question, type, required, autoFillable }` — so an agent can satisfy one (e.g. generate an `image_url` via `POST /v1/generate/image`) and re-run.

A pinned `appId` is ignored in headless mode. See the [Agent Creation Loop](/guides/agent-creation-loop) guide for the full create → satisfy → run pattern.


## OpenAPI

````yaml POST /v1/content/create
openapi: 3.1.0
info:
  title: Lamina Apps API
  version: 1.0.0
  description: >
    Professional creative content production for AI agents. Create brand-aligned
    images, videos, and designs from natural-language briefs using 30+
    specialized AI pipelines.


    Unlike raw model APIs (DALL-E, Flux, Kling), Lamina automatically applies
    brand guidelines, selects the optimal multi-model pipeline, scores output
    quality, and delivers permanent CDN-hosted URLs with composability metadata
    for chaining.


    ## Authentication

    All endpoints require an API key passed via one of these headers:

    - `x-api-key: lma_your_key` (recommended)

    - `Authorization: Bearer lma_your_key`


    API keys are workspace-scoped. Create them in **Settings -> API Keys**.


    ## Quick Start (One-Call Path)

    `POST /v1/create` with `{ "brief": "product photo of sneakers", "sync": true
    }` — returns completed output inline with CDN URL.


    ## Quick Start (Advanced)

    1. `GET /v1/apps` -- browse 30+ specialized creative apps

    2. `GET /v1/apps/{appId}` -- inspect input parameters

    3. `POST /v1/apps/{appId}/runs?webhook=<url>` -- run with your inputs

    4. Receive results via webhook, poll `GET /v1/runs/{runId}`, or stream via
    `GET /v1/runs/{runId}/stream`


    ## Rate Limits

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

    On `429`, read the `RateLimit-*` and `Retry-After` headers before retrying.


    ## How Inputs Work

    When running an app, provide inputs as a JSON object keyed by parameter
    **name** (from the app details response).


    - **text** parameters: send a string value (e.g. a prompt or description)

    - **options** parameters: send the **label** of the option (e.g.
    `"Caucasian"`), not an internal value

    - **url** parameters: send a publicly accessible URL to an image or video


    Every parameter is returned with `required: true`. Parameters with a
    `default` can safely be omitted -- the app will use the default value.


    ## Endpoint Groups

    | Group | Purpose |

    |-------|---------|

    | **Apps** | Discover and inspect available content creation apps |

    | **Runs** | Run workflows, track progress, and retrieve results |

    | **Assets** | Browse generated images, videos, and text from past
    executions |

    | **Intelligence** | Brand context, performance prediction, recommendations,
    and trends |

    | **Publishing** | Publish content to connected social channels |

    | **Content** | One-call agent operations: create, score, brief, batch |

    | **Account** | Credit balance and rate limit visibility |

    | **Templates** | Content creation templates and strategies |

    | **Webhooks** | Webhook signature verification |
servers:
  - url: https://app.uselamina.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Create
    description: Create content from briefs, run specific apps, and use templates
  - name: Discover
    description: Find and inspect available apps and their input schemas
  - name: Track
    description: Monitor execution progress, retrieve results, and browse generated assets
  - name: Intelligence
    description: >-
      Brand context, performance prediction, content recommendations, and trend
      signals
  - name: Distribute
    description: Publish content to social channels and transfer assets to CDN
  - name: Score
    description: Evaluate content quality, brand alignment, and engagement potential
  - name: Compose
    description: >-
      Turn a script into a narrated, multi-shot video — pick a format (never a
      model), preview cost, and render
  - name: Account
    description: Credit balance, rate limits, and health checks
  - name: Webhooks
    description: Webhook signature verification for secure callback handling
paths:
  /v1/content/create:
    post:
      tags:
        - Create
      summary: Plan or Create Content
      description: >
        Compatibility endpoint over Lamina's canonical frozen-plan lifecycle.

        Interactive calls return clarification questions, route choices, or an

        approval-ready plan without dispatching generation. Unattended calls
        must

        set `headless: true`, send `Idempotency-Key`, and provide a positive

        `maxCredits`; they execute only an approval-ready plan within that
        ceiling.
      operationId: createContent
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 200
          description: Required for headless execution.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                brief:
                  type: string
                  description: >-
                    Natural-language description of what content to create. This
                    is the primary input.
                platform:
                  type: string
                  nullable: true
                  description: >-
                    Target platform (e.g. `instagram`, `tiktok`, `facebook`).
                    Helps select the right app and optimize guidance.
                modality:
                  type: string
                  enum:
                    - image
                    - video
                    - audio
                  nullable: true
                  description: Desired content modality.
                brandProfileId:
                  type: string
                  format: uuid
                  nullable: true
                  description: Scope brand context to a specific brand profile.
                campaignId:
                  type: string
                  format: uuid
                  nullable: true
                  description: Scope guidance to a specific campaign.
                appId:
                  type: string
                  format: uuid
                  nullable: true
                  description: >-
                    Force a specific app instead of automatic selection. Use
                    `GET /v1/apps` to find app IDs.
                scenarioId:
                  type: string
                  maxLength: 64
                  nullable: true
                  description: Pin a known creative scenario for deterministic planning.
                feedback:
                  type: string
                  maxLength: 2000
                  nullable: true
                  description: Free-text feedback to fold into a revised plan.
                preferredPath:
                  type: string
                  enum:
                    - auto
                    - atomic
                    - compose
                    - app
                  nullable: true
                  description: >-
                    Optional route-family preference; the planner still freezes
                    the route.
                maxEstimatedCredits:
                  type: integer
                  minimum: 1
                  nullable: true
                  description: >-
                    Planning constraint; do not return a plan estimated above
                    this amount.
                headless:
                  type: boolean
                  nullable: true
                  default: false
                  description: >-
                    Execute an approval-ready frozen plan without an interactive
                    approval step. Requires Idempotency-Key and maxCredits.
                    Questions and route choices are still returned without
                    dispatch.
                maxCredits:
                  type: integer
                  minimum: 1
                  description: Required hard ceiling for headless execution.
                allowUnknownCost:
                  type: boolean
                  default: false
                  description: Explicitly allow an unknown-cost plan under maxCredits.
                inputs:
                  type: object
                  nullable: true
                  description: >-
                    Override specific input parameters on the selected app. Keys
                    are parameter names.
                templateId:
                  type: string
                  nullable: true
                  description: >-
                    Apply a content template for structured guidance. Use `GET
                    /v1/templates` to find template IDs.
                autoQuality:
                  type: object
                  nullable: true
                  description: >-
                    Auto-quality guarantee. Score output after completion and
                    retry if below threshold.
                  properties:
                    enabled:
                      type: boolean
                      default: true
                      description: >-
                        Enable auto-quality (default true when object is
                        present).
                    minScore:
                      type: number
                      default: 70
                      minimum: 0
                      maximum: 100
                      description: Minimum quality score (0-100).
                    maxRetries:
                      type: integer
                      default: 1
                      minimum: 0
                      maximum: 3
                      description: Max retry attempts (capped at 3).
                aspectRatio:
                  type: string
                  nullable: true
                  description: >
                    Output aspect ratio. Auto-mapped to the matching workflow
                    parameter. Common values: `1:1`, `16:9`, `9:16`, `4:3`,
                    `3:4`, `4:5`, `auto`.
                  example: '9:16'
                metadata:
                  type: object
                  nullable: true
                  description: >
                    Freeform context about the target placement, injected into
                    prompt engineering as structured document context. Useful
                    for passing context from the calling application without
                    manually writing it into the brief.
                  example:
                    documentTitle: Summer Collection 2026
                    fieldName: heroImage
                    fieldPurpose: Main banner image for collection landing page
                    dimensions:
                      width: 1920
                      height: 1080
                webhookUrl:
                  type: string
                  format: uri
                  nullable: true
                  description: >
                    Deprecated compatibility field. Canonical pipeline runs do
                    not attach this callback; poll GET /v1/content/runs/{runId}.
                    A warning is returned when supplied.
                  example: https://example.com/webhooks/lamina
              required:
                - brief
            example:
              brief: >-
                Create an eye-catching Instagram post showcasing our new summer
                sneaker collection with lifestyle photography
              platform: instagram
              modality: image
              brandProfileId: null
              campaignId: null
      responses:
        '200':
          description: >-
            Frozen plan, or a queued pipeline run for an authorized headless
            request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Frozen plan, or a bounded headless pipeline run.
              example:
                data:
                  status: plan
                  canonicalStatus: awaiting_approval
                  planId: fc32ae7d-6840-4be3-8fb1-539a60e33fc3
                  planFingerprint: sha256-fingerprint
                  estimatedCredits: 12
                  plan:
                    status: awaiting_approval
                    steps: []
        '400':
          description: Invalid brief, modality, planner constraint, or headless budget.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: brief is required (string)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Error:
      type: object
      description: Standard error response
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: string
          description: Additional validation error details (present on 400 responses)
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          example:
            error: Invalid API key
    TooManyRequests:
      description: >-
        Rate limit exceeded. All `/v1/*` endpoints are currently limited to 100
        requests per minute per IP.
      headers:
        RateLimit-Policy:
          description: Active rate limit policy.
          schema:
            type: string
            example: 100;w=60
        RateLimit-Limit:
          description: Max requests allowed in the current window.
          schema:
            type: integer
            example: 100
        RateLimit-Remaining:
          description: Requests remaining in the current window.
          schema:
            type: integer
            example: 0
        RateLimit-Reset:
          description: Seconds until the current window resets.
          schema:
            type: integer
            example: 60
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            example: 60
      content:
        text/plain:
          schema:
            type: string
          example: Too many requests from this IP, please try again in a minute
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Workspace API key. Prefix: `lma_`. Example: `lma_abc123...`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.