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

# AI media generation

> Generate images and sound effects from a text prompt and place them in a video.

When there is nothing to upload, generate it: the same AI image and sound effect generators the editor's media panels use are available as tools. Generation is asynchronous — each tool returns a `generation` whose `id` is the private library item being filled in. Poll `get_generation_status` until it is `completed`, then place `generation.item.sourceId` with the usual placement tools. Every generation counts against your plan's weekly AI generation allowance.

## generate\_image

Generate a landscape image (2048×1152) from a text prompt. Usually takes 30-90 seconds. Once complete, place the item's `sourceId` with `add_overlay` for an image overlay, or with `add_layout` (`media: {type: "image", sourceId}`) for a b-roll still.

<ParamField path="prompt" type="string" required>
  What to generate — subject, style and composition, up to 4000 characters
</ParamField>

<ParamField path="referenceSourceId" type="string">
  The `sourceId` of an image source to guide the generation — from `create_source` (`kind: "image"`) after uploading, or an `image` item in `list_library`
</ParamField>

Returns a `generation` (`id`, `type`, `status`, `prompt`) plus the weekly allowance (`limit`, `remaining`, `resetAt`).

## generate\_sound\_effect

Generate a short sound effect from a text prompt, for when Tella's curated catalog (`list_library` with `scope: "default"`) has nothing suitable. Usually takes 10-30 seconds. Once complete, place the item's `sourceId` with `add_sound_effect` (as `sourceId`, not `presetId`).

<ParamField path="prompt" type="string" required>
  The sound to generate, e.g. "soft camera shutter click", up to 2000 characters
</ParamField>

Returns a `generation` plus the weekly allowance (`limit`, `remaining`, `resetAt`).

## get\_generation\_status

Poll this after a generate tool until `generation.status` is `completed` or `failed`. While it is `pending` or `running`, wait a few seconds and call again. On `completed`, `generation.item` is the finished library item — pass its `sourceId` to `add_overlay`, `add_sound_effect`, `add_layout` or `apply_video_edits`. On `failed`, `generation.error` provides a sanitized, human-readable reason that may identify a content-safety rejection or timeout, or report a generic failure. Do not parse this text for machine handling; start a new generation.

<ParamField path="generationId" type="string" required>
  The `generation.id` returned by a generate tool
</ParamField>


## Related topics

- [Generate media with AI](/docs/api-reference/library/generate-media-with-ai.md)
- [Get a generation's status](/docs/api-reference/library/get-a-generations-status.md)
- [Model Context Protocol (MCP)](/docs/mcp-server.md)
- [Media library API](/docs/media-library-api.md)
- [Add media (B-roll)](/docs/help/editing/use-media.md)