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

# How Kynva works

> AI proposes, the compiler decides, the renderer renders. Deterministically.

Kynva is a **deterministic design engine**. The same input always produces byte-identical pixels. That property — determinism — is what makes the API safe to use in production pipelines, A/B systems, and CI.

## The pipeline

```
Brief  ──►  Compile  ──►  Spec  ──►  Render  ──►  Pixels
 (intent)   (decisions)  (frozen)   (no choices)  (PNG/MP4/...)
```

| Stage       | What it does                                                                         | What it doesn't do                                         |
| ----------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| **Brief**   | Captures user intent — copy, mood, audience, brand.                                  | Doesn't specify layout, type sizes, or color values.       |
| **Compile** | Resolves intent against your BrandKit and the design system. Every choice is pinned. | Doesn't render pixels.                                     |
| **Spec**    | Frozen JSON contract — colors as hex, fonts as IDs, positions in px.                 | Has no free variables. Identical Specs render identically. |
| **Render**  | Pure transformation from Spec to pixels.                                             | Makes no design decisions.                                 |

## What this means for you

<AccordionGroup>
  <Accordion title="Reproducibility — same input, same output">
    A Spec is content-addressable. If you keep the Spec, you can re-render the exact pixels months later. There are no model temperature surprises.
  </Accordion>

  <Accordion title="Explainability — see every decision">
    Every compile step writes a `decisions` log: why this font, why this color, which fallback fired. Audit trails come for free.
  </Accordion>

  <Accordion title="Composition — branch and iterate cheaply">
    Drafts are versioned. Branch a Draft, tweak the brief, recompile. The expensive part (render) is skipped until you preview.
  </Accordion>

  <Accordion title="Safety — the compiler enforces brand">
    Style-lock rules in your BrandKit are enforced at compile time. If a brief asks for a color that violates the lock, the compiler rejects it with [`STYLE_LOCK_VIOLATION`](/errors/codes#style-lock-violation) — before any pixels render.
  </Accordion>
</AccordionGroup>

## The API surface

One canonical endpoint, two modes:

### Sync preview

```
POST /api/v1/facade/generate   { "operation": "preview" }   → 200 + outputs
```

The response carries the rendered image URLs. Best when someone is waiting.

### Async render

```
POST /api/v1/facade/generate   { "operation": "render" }    → 202 + job
GET  /api/v1/facade/render-jobs/{job_id}                     → status poll
```

Consume the job via [webhooks](/webhooks/overview), the status poll, or the
SSE stream. Best for pipelines and batches — see the
[async guide](/guides/async-render-jobs).

### Signed image URLs — the shortcut

```
POST /api/v1/generate/sign        → signed URLs (batch ≤100)
GET  /api/v1/generate/{template}  → 302 to the rendered PNG
```

URLs that render on first fetch and cache forever. Built for OG images and
no-code embeds — no Authorization header needed at fetch time.

## What you'll meet across every endpoint

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/concepts/authentication">
    `Authorization: Bearer kyn_live_...` on every request.
  </Card>

  <Card title="Idempotency" icon="repeat" href="/concepts/idempotency">
    `Idempotency-Key: <uuid v4>` on every POST mutation.
  </Card>

  <Card title="Versioning" icon="code-branch" href="/concepts/api-versioning">
    `X-API-Version: 2026-01-01` pins the response shape.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/concepts/rate-limits">
    Tiered per endpoint category, surfaced in headers.
  </Card>
</CardGroup>