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

# Agentic Workflows

> Tools and integrations for building AI-driven video personalization workflows with Nexrender Cloud

Nexrender Cloud exposes a set of tools that work well together for AI-driven video personalization. Rather than requiring hardcoded layer names and asset mappings, agents can discover template structure at runtime, generate assets dynamically via AI providers, and submit jobs at scale - all through the same REST API used for standard automation.

## The Nexrender Skill

The [Nexrender skill](https://github.com/nexrender/nexrender-skill) packages API reference into a format that Claude and other LLM agents can load at runtime. It covers job payload structure, asset types, output settings, codec identifiers, secret references, font resolution, and common failure patterns - so an agent has correct, grounded knowledge of the API without relying on general training data.

Load the skill into your Claude/Codex-based agent or MCP environment before asking it to construct job payloads or introspect templates. The skill works alongside live API responses: the agent brings API knowledge, the API brings runtime template data.

## Layer and Composition Analytics

The `/v3/templates/{id}/compositions` and `/v3/templates/{id}/layers` endpoints expose the After Effects structure of a template as machine-readable data. Agents can use this to work generically against any template rather than relying on prior knowledge of its layer names or structure.

**Compositions** (`GET /api/v3/templates/{id}/compositions`) return:

| Field              | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| `name`             | Composition name - used as `template.composition` when submitting jobs |
| `width` / `height` | Canvas dimensions in pixels                                            |
| `duration`         | Duration in seconds                                                    |
| `frame_rate`       | Frames per second                                                      |

**Layers** (`GET /api/v3/templates/{id}/layers`) return:

| Field                    | Description                                                                    |
| ------------------------ | ------------------------------------------------------------------------------ |
| `name`                   | Layer name - used as `layerName` in job assets                                 |
| `layer_type`             | `TextLayer`, `AVLayer`, `ShapeLayer`, `CameraLayer`, `LightLayer`, `NullLayer` |
| `source_type`            | For `AVLayer`: `image`, `video`, or `audio`                                    |
| `width` / `height`       | Layer bounding box in pixels                                                   |
| `top` / `left`           | Layer position on the canvas                                                   |
| `in_point` / `out_point` | Visible time range in seconds                                                  |
| `composition_id`         | The `aeid` of the parent composition                                           |

Both endpoints support `limit` (default 300, max 1000) and `offset` for pagination.

See [Template Introspection](/docs/cloud/templates/inspecting) for full response shapes and status polling.

## AI Content Generation

The `nx:genai` function calls an external AI media provider at render time and injects the generated asset into a specified layer before After Effects composites the frame. As of now, the only supported provider is **fal.ai** - please reach out to support, so we could prioritize adding new providers.

```json theme={null}
{
  "type": "function",
  "name": "nx:genai",
  "params": {
    "provider": "fal",
    "key": "${secret.FAL_KEY}",
    "model": "fal-ai/flux/schnell",
    "type": "image",
    "layerName": "hero-image",
    "data": {
      "prompt": "Abstract tech landscape, purple tones, dark background"
    }
  }
}
```

The `data` object is passed directly to the fal.ai model. Its shape depends on the model - refer to the [fal.ai model library](https://fal.ai/models) for available models and their input schemas. The `type` field controls how the result is injected: `image` replaces the layer's footage source; `video` does the same and can be followed by `nx:layer-duration-set` to match the composition duration to the generated clip length.

Store your `FAL_KEY` as a Nexrender secret (see below) and reference it with `${secret.FAL_KEY}` rather than embedding the value in the payload. See [Secrets Management](/docs/cloud/jobs/secrets) for the full API. See [`nx:genai`](/docs/cloud/jobs/functions/nx-gen-ai) for the full parameter reference.

## Webhooks

Add a `webhook.url` to any job or batch payload and Nexrender will POST the completed job object to your endpoint when it reaches a terminal state (`finished` or `error`). This is the preferred pattern for agent workflows - it avoids polling and lets the agent react immediately to render completion.

```json theme={null}
{
  "webhook": {
    "url": "https://yourdomain.com/webhooks/render-complete"
  }
}
```

Your endpoint must return a `2xx` response. Nexrender retries up to 3 times with exponential backoff on non-2xx responses or connection failures.

See [Tracking Renders](/docs/cloud/jobs/tracking_renders) for webhook payload shape and polling as a fallback.

## Batch Jobs

`POST /api/v2/batches` accepts up to 1,000 job payloads in a single request. Each job in the batch is a standard job payload - the same template, assets, settings, and webhook fields. Nexrender creates all jobs atomically and returns aggregate progress via `GET /api/v2/batches/{id}`.

Batches support partial success: failed jobs appear in an `errors` array while successful ones proceed. This makes batches suitable for large personalisation runs where individual record failures should not block the rest.

See [Batch Jobs](/docs/cloud/jobs/batch_jobs) for the full request and response schema.

## Getting Started

1. **Install the skill** from [github.com/nexrender/nexrender-skill](https://github.com/nexrender/nexrender-skill) into your Claude or MCP environment
2. **Store credentials** - add your Nexrender API key and any provider keys (e.g. `FAL_KEY`) as secrets
3. **Upload a template** and confirm its status is `uploaded`
4. **Inspect the template** using the compositions and layers endpoints to discover its structure
5. **Submit a job** using layer names and composition names from the introspection response

## Related

* [Template Introspection →](/docs/cloud/templates/inspecting)
* [Initiating Renders →](/docs/cloud/jobs/initiating_renders)
* [AI Content Generation (nx:genai) →](/docs/cloud/jobs/functions/nx-gen-ai)
* [Batch Jobs →](/docs/cloud/jobs/batch_jobs)
* [Secrets Management →](/docs/cloud/jobs/secrets)