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. Images and video clips need a paid plan (a free trial is refused with a message to upgrade), are charged in your workspace’s AI Credits, and are refused while the balance doesn’t cover them; sound effects count 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. Each image is charged in the workspace’s AI Credits, and generation is refused during a free trial or while the balance is empty. Once complete, place the item’ssourceId with add_overlay for an image overlay, or with add_layout (media: {type: "image", sourceId}) for a b-roll still.
string
required
What to generate — subject, style and composition, up to 4000 characters
string
The
sourceId of an image source to guide the generation — from create_source (kind: "image") after uploading, or an image item in list_librarystring
default:"sunburst"
sunburst (most capable, follows reference images most precisely) or flare (faster)generation (id, type, status, prompt).
generate_video
Generate a short b-roll video clip from a text prompt. Takes several minutes. Once complete, place the item’ssourceId with add_layout (media: {type: "video", sourceId} over a time range) for b-roll, or with add_overlay for a video overlay; generation.item.durationMs is the clip’s length. Each clip is charged in the workspace’s AI Credits, and generation is refused during a free trial or while the balance is empty.
string
required
What the clip should show — scene, motion and style, up to 2000 characters
string
The
sourceId of an image source to use as the clip’s first frame — from create_source (kind: "image") after uploading, or an image item in list_library. On seedance-2.5 the clip keeps the image’s aspect ratio; the 2.0 models crop to 16:9. An image that shows a person, real or AI-generated, is refused.string
default:"seedance-2.5"
seedance-2.5 (best quality, 1080p), seedance-2.0-fast (quicker and cheaper, 720p) or seedance-2.0-mini (cheapest, 720p).integer
default:"5"
The clip’s length in whole seconds: 4–30 on
seedance-2.5, 4–15 on the 2.0 models. A longer clip costs proportionally more credits and takes longer to generate.generation.
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).
string
required
The sound to generate, e.g. “soft camera shutter click”, up to 2000 characters
generation plus the weekly allowance (limit, remaining, resetAt).
get_generation_status
Poll this after a generate tool untilgeneration.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.
string
required
The
generation.id returned by a generate tool