# Generate via API (authenticated)

Use layer overrides to dynamically customize your template. Each override targets a layer by its
name and replaces the values you supply, leaving the rest of the template untouched.

```javascript
const response = await fetch('https://yourdomain.com/api/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: 'your-template-id',
    layers: {
      title: { text: 'My Blog Post Title' },
      subtitle: {
        text: 'Published on Jan 15',
        fontSize: 24,
        color: '#666666'
      },
      logo: {
        image_url: 'https://example.com/logo.png',
        width: 120,
        height: 120
      }
    },
    format: 'png',  // 'png' (default), 'jpeg', 'webp', or 'pdf'
    quality: 80     // 1-100 for jpeg/webp; ignored for png and pdf
  })
});

const { success, imageUrl, cached, warnings } = await response.json();
// warnings (optional) lists any image that failed to load or an
// unresolved asset reference — the render still returns 200.
// Use imageUrl in your application
```

The public `/api/render` endpoint always returns PNG; use `/api/generate` with `format` for JPEG,
WebP, or PDF output.

> **Note: PDF output**
>
> `format: 'pdf'` returns a single-page vector PDF instead of a raster image, sized to the template's width and height in px. It's a normal render like any other format, billed the same way with no plan gating. `scale` and `quality` are both ignored, since a vector page has no pixel density or lossy compression to tune.

## Layer override reference

Each override targets a layer by its **name** and must match the shape for that layer's type. Any
subset of fields works — override just `fontSize` without `text`, or just `objectFit` without
`image_url`. The full typed schemas (`TextLayerOverrides`, `ImageLayerOverrides`,
`ShapeLayerOverrides`) are in the [API Reference](/api/openapi).

```text
Text layers   text, fontSize, fontWeight, fontStyle, fontFamily, color,
              textAlign, verticalAlign, lineHeight, letterSpacing,
              textTransform, textDecoration, backgroundColor,
              borderRadius, width, height, rotation

Image layers  image_url, objectFit, objectPosition, borderRadius,
              border, opacity, width, height, rotation

Shape layers  fill, opacity, borderWidth, borderColor, borderStyle,
              borderRadius, width, height, rotation
```

> **Warning: Strict validation**
>
> A malformed override — a bare value instead of an object (`{ "title": "Hello" }` instead of `{ "title": { "text": "Hello" } }`), an unknown field, or a wrong type — is rejected with a **400** that names the offending layer and field. Text content is set with `text` (not `content`), image sources with `image_url` (not `src`).

> **Note: Warnings**
>
> An override that names a layer that doesn't exist in the template, or carries fields the layer's type can't use, renders fine but is reported in the response's `warnings` array (or the `X-Render-Warnings` header on `/render`) as `override_ignored`.