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

# nx:genai

> Generate an AI video, image, or audio file and place it in a footage layer of your template

The `nx:genai` function asks an AI media provider to generate a video, image, or audio file. The generated file then replaces the footage of a layer in your After Effects template, and the render continues with it.

## How It Runs

The API creates a separate generation job for each `nx:genai` function in your `assets` array. Your render job waits until that job finishes:

* The job creation response has status `pending` and lists the generation job in a `children` array, with `"function": "nx:genai"`.
* When the generation job finishes, the generated file replaces the footage of `layerName`, and your render job is queued.
* The generation job is not retried. If generation fails, your render job fails too.
* If your render job is retried, it reuses the generated file. The provider is not called again.
* The generated file is uploaded to the same storage as your render output.
* Each `nx:genai` function counts as a nested job toward the limits on how many jobs and levels one job tree can have. See [Nested Jobs](https://www.nexrender.com/docs/cloud/jobs/nested_jobs.md).

## Parameters

**provider** `string` *required*

The AI provider to call. The only supported value is `fal`.

**key** `string` *required*

API key for the provider. Use a [secret reference](https://www.nexrender.com/docs/cloud/jobs/secrets.md) such as `${secrets.FAL_KEY}` instead of the key itself.

**model** `string` *required*

The model identifier on the provider's platform. The exact value depends on which model you want to use - refer to your provider's model library for available options.

**type** `string` *required*

The kind of file the model returns: `video`, `image`, or `audio`. The generated file is added to the layer as an asset of this type.

**layerName** `string` *required*

Name of the footage layer that receives the generated file. Pass a single name. Arrays are not accepted for this function.

**data** `object` *required*

Model-specific parameters passed directly to the provider's API. The shape of this object varies by model - refer to your provider's documentation for the full list of available fields.

## Example

The following example uses FAL.AI to generate a talking-head video of a character speaking a provided script, then places it in a footage layer:

```json theme={null}
{
  "type": "function",
  "name": "nx:genai",
  "params": {
    "provider": "fal",
    "key": "${secrets.FAL_KEY}",
    "model": "infinitalk/single-text",
    "type": "video",
    "layerName": "var_video",
    "data": {
      "image_url": "https://example.com/character.jpg",
      "text_input": "A Victorian inventor journeys to the distant future, encountering the peaceful Eloi and the subterranean Morlocks.",
      "voice": "Eric",
      "prompt": "A young man with a beard records audio with a microphone. He appears engaged and expressive, suggesting a podcast or voiceover.",
      "num_frames": 721,
      "resolution": "720p",
      "acceleration": "high"
    }
  }
}
```

The `data` fields here are specific to the `infinitalk/single-text` model - a different model would expect a different set of parameters. Always consult the model's documentation on the provider platform for the exact payload shape.

## Video Length

Nexrender does not measure the generated clip. It does not change the length of any layer or composition to match it.

To control the length, ask the model for a specific length in `data` (for example `num_frames` in the example above). Then set the same length, in seconds, on your template:

* [`nx:layer-duration-set`](https://www.nexrender.com/docs/cloud/jobs/functions/nx-layer-duration-set) sets the duration of the layer that holds the clip.
* [`nx:comp-duration-set`](https://www.nexrender.com/docs/cloud/jobs/functions/nx-comp-duration-set) sets the work area of the composition, which sets how long your output is.

Both functions require `value`. Add them after `nx:genai` in your `assets` array:

```json theme={null}
[
  {
    "type": "function",
    "name": "nx:layer-duration-set",
    "params": {
      "layerName": "var_video",
      "value": 30
    }
  },
  {
    "type": "function",
    "name": "nx:comp-duration-set",
    "params": {
      "composition": "Main Comp",
      "value": 30
    }
  }
]
```

If the model returns a clip of a different length, the layer and work area still use your `value`.

## Storing Your Provider Key as a Secret

Never embed provider API keys directly in a job payload. Store them as Nexrender secrets and reference them with the `${secrets.NAME}` syntax - see [Secrets Management](https://www.nexrender.com/docs/cloud/jobs/secrets.md) for details.


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