Full API Reference

Must be `client_credentials`.

The OAuth client id created in the developer portal.

The OAuth client secret shown only when the client is created.

Optional space-separated scopes. Omit to receive the client’s default scopes.

Public CLI client id. Currently only `genfire-cli`.

BASE64URL(SHA256(code_verifier)). 43-128 characters.

Must be `S256`.

Optional list of scopes the CLI is requesting. Omit for the default key scopes.

Optional human label shown to the user on the consent page (e.g. `genfire-cli (laptop)`).

Session id returned from `POST /cli/auth/sessions`.

Session id returned from `POST /cli/auth/sessions`.

The original PKCE code_verifier the CLI generated when starting the session.

Read this workspace's shared pool instead of the personal balance (`GET /v1/teams`). Requires the `teams:read` scope; 404 `invalid_team_id` when you are not a member.

Model alias from GET /v1/models, e.g. video.seedance_2_0.

Video/image resolution (e.g. 720p, 1080p, 4k, 2K).

Video duration in seconds (also used for lipsync audio when no audio_url).

Whether audio is generated (affects some video models).

Number of outputs (video/image).

Image quality tier — GPT Image 2 / Genfire (low/medium/high) and Grok Imagine 2.0 (low/medium).

3D: include base-color textures (default true).

3D: include PBR maps.

3D: include auto-rigging.

Speech text (character_count derived from length).

Speech character count (alternative to text).

Music / SFX duration in seconds.

Lipsync: audio URL (duration estimated when duration omitted).

Comma-separated extra sources to include. Currently only `stock` is supported, which appends built-in ElevenLabs voices.

Inclusive lower bound (ISO date or full timestamp). Defaults to 30 days ago.

Exclusive upper bound. Defaults to now.

Bucketing for the breakdown: `model`, `capability`, `day`, or `none`.

Default: model

Optional filter, e.g. `video_generation`.

Original filename. The extension is preserved in the stored object path.

MIME type for the upload. Pinned into the signed URL — the PUT must send the same `Content-Type`.

Default: application/octet-stream

Optional declared file size. Rejected if greater than the 5 GB ceiling.

Influencer id from `GET /v1/influencers`.

Short @-mention handle (letters, digits, underscores), e.g. `maya`. Lowercased automatically. Must be unique within your account. This is the influencer's only name — the `display_name` in responses is derived from it.

FROM-PHOTOS mode. 1–8 absolute https URLs of reference photos. Upload local files via `POST /v1/uploads` first and pass the returned `asset_url`s here. Mutually exclusive with `appearance`.

FROM-SCRATCH mode. Generate a new person from traits. Fields: `gender` (string, required — e.g. "woman", "man"), `heritage` (string, required — race/ethnicity, e.g. "korean"), `age` (string, required — one of `18-21`, `21-25`, `25-30`, `30-40`, `40+`), `prompt` (string, optional — free-text descriptor, e.g. "freckles, platinum bob, green eyes, editorial look"). Mutually exclusive with `photo_urls`.

Filter. A root project id lists only that project's folders; the literal `root` lists only top-level projects. Omit for the whole tree.

Project id from `GET /v1/projects`.

Project name, e.g. `Summer Campaign` or `Scene 01`.

Optional short description.

Create this as a folder inside the given ROOT project. The parent must be a root the caller can edit.

Project id from `GET /v1/projects`.

New project name.

The project's creative brief, shown in the studio and returned by `GET /v1/projects/{projectId}`.

Move this project under a root project, or `null` to promote it to a root. One-level nesting is enforced: a project that already has folders cannot become a folder.

Project id from `GET /v1/projects`.

Project id from `GET /v1/projects`.

Assets to file. Each is `{ asset_id, asset_type }` where `asset_type` is one of `video`, `image`, `audio`, `element`, plus an optional `title` and `thumbnail_url`. Image and video ids come from a completed run (`resource_id`, or `internal_refs.image_ids`); element ids from `GET /v1/elements`.

Project id from `GET /v1/projects`.

Asset ids to unfile, from `GET /v1/projects/{projectId}` items.

Element id from `GET /v1/elements`.

Human-friendly name, e.g. `Red Bottle`. Also used as the in-prompt phrase ("the Red Bottle") when the `@handle` is resolved.

Absolute https URL of the element image. Upload a local file via `POST /v1/uploads` first and pass the returned `asset_url`.

Short @-mention handle (letters, digits, underscores), e.g. `redbottle`. Lowercased automatically. Auto-derived from `name` if omitted. Must be unique within your account.

Optional aspect ratio of the image, e.g. `1:1`, `9:16`. Informational only.

File the new element into one of your PROJECTS (`GET /v1/projects`), the same way the studio files an element created while a project is open. Access is checked before the element is created; the response echoes `project_id` (null if filing failed).

Element id from `GET /v1/elements`.

The brand or product website URL, e.g. `https://example.com`. A bare domain is accepted (https is assumed).

Brand name.

Short positioning line.

What the brand sells and who it serves.

Stored for reference only — this endpoint never visits it.

URL of an already-hosted logo image.

URL of an already-hosted icon or favicon.

Palette entries, e.g. `[{ "hex": "#FF5A1F", "role": "primary" }]`.

Typography entries, e.g. `[{ "name": "Inter", "role": "heading" }]`.

Structured brand voice (tone, do/dont, vocabulary).

Free-text visual style direction.

Reference imagery already hosted elsewhere.

BCP-47 language tag, e.g. `en-US`.

ISO 3166-1 alpha-2 country code, e.g. `US`.

Brand id from `GET /v1/brands` or a completed ingestion run's `output.brand_id`.

Brand id.

Brand id.

Moodboard id from `GET /v1/moodboards` or a forked preset.

Preset id from `GET /v1/moodboards/presets`.

Team id from `GET /v1/teams`.

The video to analyse. Provide exactly one of video_url or youtube_url.

A YouTube link to analyse. Provide exactly one of video_url or youtube_url.

`summary` (3–6 major movements), `scenes` (one entry per meaningful beat), or `shot-list` (one entry per camera setup, for a shot-for-shot recreation).

Default: scenes

Bill a workspace pool instead of your balance (`GET /v1/teams`). You must be a member with a spending role.

The brand to store the product on (`GET /v1/brands`). Must be a brand you own.

The product page to read.

Override the scraped product name. Required when the page yields none.

Override the scraped description.

Free-text match over title, description, ad format and the recipe prompt. Every whitespace-separated term must appear, so extra words narrow the result.

One of `product-shot`, `motion`, `ugc`, `ads`, `posters`, `marketplace`. See `GET /v1/marketing/ad-formats`.

`image` or `video`. An image template runs through `/images/generations`; a video template through `/videos/generations`.

Set `true` for templates with a person in frame (those offering or requiring an avatar slot).

Page size, 1–100.

Default: 24

`next_cursor` from the previous page.

Template id from `GET /v1/marketing/templates`.

Match over id, label, description and the fragment itself.

`image` or `video` — several genres are one or the other only.

Only genres most at home on this shelf. A hint, never a restriction.

Match over id, label, description, type and the fragment itself.

`image` or `video`. Most hooks are video-first — an opening beat needs time to happen.

`stunt` or `subtle`.

Match over id, label, description, category and the fragment itself.

`realistic` or `unrealistic`.

Match over name, handle and the scene/gender/age tags.

`user` for your trained influencers only, `preset` for the house library only. Omit for both.

House-library scene tag: ugc, car, studio, podcast, interview, lifestyle, office, outdoor.

male, female, or neutral (house library only).

young-adult, adult, middle-aged, or senior (house library only).

Page size, 1–100.

Default: 24

`next_cursor` from the previous page.

Match over product name, description, brand name and USPs.

Restrict to one brand (`GET /v1/brands`).

Page size, 1–100.

Default: 24

`next_cursor` from the previous page.

What game to build — or, with `game_id`, the change to make (e.g. "make it faster, add a boss").

Iterate on an existing game: pass the `game_id` from a prior generation. The stored game is re-generated in place at the same `play_url`.

Codegen model alias (e.g. `claude-opus-5`, `claude-sonnet-5`). Defaults to Opus.

Up to 16 asset URLs (images / GLB / audio from other Genfire endpoints) to wire into the game as sprites, textures, or sound.

Build with realtime multiplayer via the Genfire relay. Players join with the same `?room=` link.

Default: false

The `game_id` of a completed game from `POST /games/generations`.

true (default) to publish to the public gallery; false to unpublish.

Default: true

Optional run status filter such as `queued`, `processing`, `completed`, or `failed`.

Optional capability filter such as `image_generation` or `workflow.hook_pack`.

Optional in-product surface filter — e.g. `marketing-studio`. Returns the runs made in that surface from BOTH origins: pieces created in the Genfire dashboard AND ones created through this API with the surface's own parameters (a `marketing_template_id` run tags itself the same way the dashboard bar does), so it is that surface's whole history rather than an API-only slice. Every run's own surface is echoed back as `app`. Runs that named no surface have `app: null` and are excluded whenever this filter is set. Uses the deep-scan path, so the response also carries `scanned` and `has_more`.

Maximum number of runs to return.

Default: 25

The run id returned by the API.

LONG-POLL: hold the request until the run reaches a terminal state (`completed` or `failed`) or this many seconds elapse, then return whatever state the run is in. Accepts 0–30 (values above 30 are capped, not rejected); omit or pass 0 for the default immediate response. One long-poll costs one request against your rate limit however long it is held, so `?wait=30` uses roughly a fifteenth of the requests a 2s polling loop would. A non-numeric value returns 400 `invalid_wait`.

Default: 0

The run id returned by the API.

The image prompt. May include @<handle> mentions when paired with a `mentions` array.

Optional image model alias from `/models`. Models with an internal edit variant accept `mentions`, `image_url`, and `image_urls` for influencer-conditioned or multi-image edits.

Default: image.nano_banana_2

Image aspect ratio.

Default: 1:1

Number of images to generate, from 1 to 4.

Default: 1

Optional single source image URL. When provided with an edit-capable model, the request is routed through the model's edit variant. Use `image_urls` for multi-image edits.

Optional list of up to 14 source image URLs for a multi-image edit. Supported by GPT Image 2, Seedream, Qwen Image 2 and Nano Banana; Grok uses at most the first 3. Routes through the model's edit variant.

Optional MASKED INPAINT: an absolute http(s) URL to a mask image (white = repaint, black = keep) the same size as the source. Only the white region is regenerated; everything else is preserved. Requires `image_url` (or `image_urls`) — a mask alone is rejected with 400 `mask_requires_source_image`. Only accepted by models whose `capabilities.masked_inpaint` is true on `GET /v1/models` (image.gpt_image_2, image.genfire_v1, image.nano_banana_2, image.nano_banana_pro); any other model returns 400 `model_lacks_mask_support` rather than silently ignoring the mask and billing a full-frame rewrite. Upload the mask with `POST /v1/uploads` and pass the returned `asset_url`; data: URIs are rejected with 400 `invalid_mask_url`, and the URL is checked against the same SSRF guard as every other caller-supplied URL (400 `unsafe_outbound_url`).

Optional `[{ handle, influencer_id }]` to inject a trained influencer character into the image. The model is auto-switched to its edit variant and the influencer's reference photos are added as conditioning. Currently a single mention per request is supported.

Optional id of one of your brands (`GET /v1/brands`). Grounds the generation server-side: the brand's real product images are attached as edit sources and its colors/style/voice are prepended to the prompt. Invalid or unowned id → 404 `invalid_brand_id`.

Optional id of one of your moodboards (`GET /v1/moodboards`, or a board shared with you). Requires the `moodboards:read` scope in addition to `images:write` (403 `insufficient_scope` otherwise — the board's style text echoes back through the run record). Styles the generation server-side: the board's composed style fragment is prepended to the prompt and its exemplar images are attached as edit sources. Composes with `brand_id` — the brand prefix leads and brand references take the reference slots first. Unknown or inaccessible id → 404 `invalid_moodboard_id`; other resolution failures → 400 `invalid_moodboard_id`. On models without an internal edit variant the style applies as prompt text only (no exemplar attachment). The run's `input` records `moodboard_id` and `moodboard_strength`, so `GET /runs/{id}` shows what styled the run.

How hard the moodboard steers: `subtle` (prompt fragment only, no reference images), `balanced` (fragment + up to 3 exemplars), or `strong` (fragment + as many exemplars as fit under the 14-image cap). Any other value → 400 `invalid_moodboard_strength`. Only meaningful with `moodboard_id`.

Default: balanced

File this generation's output into one of your PROJECTS (`GET /v1/projects`) the moment the run completes — the same thing the Video Studio does when you have that project open. Access is checked before the run is created, so an unknown id or one you cannot edit is a 404 `project_not_found` / 403 `project_forbidden` at request time rather than a silently unfiled result. Filing itself is best-effort and never fails a run you have already paid for. The run echoes it back as `project_id`.

Bill this generation to a WORKSPACE (team) credit pool instead of your balance (`GET /v1/teams`). Membership and a spending role are asserted before the run is created — 404 `invalid_team_id` when you are not a member, 403 `team_role_cannot_spend` when your role cannot spend. Requires the `teams:read` scope. The run echoes it back as `team_id`.

Optional id of a Marketing Studio ad template (`GET /v1/marketing/templates`). Composes the request server-side from the template RECIPE: the recipe prompt has its `{{product}}` / `{{avatar}}` tokens replaced with the positions your slot media is actually sent in, the slot media is emitted in the recipe's own `slot_order` AHEAD of any brand/moodboard references, and the template's model, aspect ratio, resolution and count are applied unless you pass your own. Fill the fields the template lists under `recipe.required_inputs`; a missing one → 400 `marketing_slot_missing`. Passing a template for the other media type → 400 `marketing_template_mode_mismatch`. Unknown id → 404 `marketing_template_not_found`. A template whose model has no /v1 alias → 400 `template_model_unavailable` (pass an explicit `model` to run it anyway). A `prompt` you send alongside is ADDITIVE — it says what to CHANGE, so do NOT re-send the recipe prompt.

Optional GENRE (`GET /v1/marketing/formats`) — unboxing, tutorial, before-after, star review, comparison and so on. Fragments compose in the order genre → hook → setting, so the genre defines the piece, the hook claims its opening beat, and the setting relocates whatever those produced. WITH `marketing_template_id` the recipe is the base and the three fragments follow it, with your own `prompt` last as a change note. WITHOUT a template your `prompt` IS the base subject description and the fragments are directives applied to it, so they follow your prompt instead. Works WITHOUT a template. Unknown id → 400 `invalid_marketing_format_id`; a genre that does not apply to this media type → 400 `format_mode_mismatch`.

Optional OPENING MECHANIC (`GET /v1/marketing/hooks`) — a physical event in the first two seconds, not a copy angle: the product flying at the creator, an indoor blizzard, the camera being knocked, a held silence. `stunt` or `subtle`. Independent of the format, so any hook can open any genre. Works WITHOUT a template. Unknown id → 400 `invalid_marketing_hook_id`; a hook that does not apply to this media type → 400 `hook_mode_mismatch`.

Optional ENVIRONMENT (`GET /v1/marketing/settings`) — `realistic` (marble kitchen, gym floor, golden hour) or `unrealistic` (airplane wing, volcano rim, shrunk to doll size). Written as a relocation directive so it overrides the scene a template describes. Works without a template. Unknown id → 400 `invalid_marketing_setting_id`.

Fills the template's PRODUCT slot. Takes precedence over `product_id`.

Fills the template's AVATAR slot — who appears in the ad. Takes precedence over `avatar_id`. Rejected with 400 `avatar_not_supported_by_template` on a start-frame video template, which animates the product photo itself and has no avatar slot.

Fills the PRODUCT slot from your stored brand products (`GET /v1/marketing/products`) — no re-upload. Unknown or imageless id → 400 `invalid_product_id`.

Fills the AVATAR slot from your trained influencers or the house avatar library (`GET /v1/marketing/avatars`). Accepts the prefixed id (`influencer:abc`, `preset:xyz`), a bare influencer id, or an @handle. Unknown id → 400 `invalid_avatar_id`.

Quality tier. image.gpt_image_2 / image.genfire_v1: low, medium, high, auto — cost low=1×, medium=6×, high=22×. image.grok_imagine_2: low or medium only, priced as separate base rates (low is cheaper); anything else is rejected.

Default: medium

Output resolution: 1K, 2K, 4K. image.grok_imagine_pro and image.grok_imagine_2 accept 1K/2K on BOTH the text-to-image and edit paths (4K is rejected). Nano Banana family (image.nano_banana, image.nano_banana_2, image.nano_banana_pro) is edit-only — the request must supply image_url or mentions to route through the model edit variant. Affects cost: 1K=1×, 2K=1.5×, 4K=3×.

When true, returns the QUEUED run immediately and generates in the background — poll `GET /runs/{id}` (or subscribe to webhooks) for completion, exactly like video. Credits are pre-checked up front (402 on insufficient balance). Defaults to false (the request holds until the images are ready). The same request dedupes to the same run whether called sync or async.

Default: false

The video prompt.

Optional video model alias from `/models`.

Default: video.veo_3_1

Video aspect ratio.

Default: 16:9

Target duration in seconds.

Default: 5

Output resolution (e.g. 480p, 720p, 1080p, 4k). Supported values and pricing are per-model — see `resolutions` under `/models`. Higher resolutions cost more credits.

Source image for image-to-video, or character image for motion-control.

Source video for video-edit, video-extend, or motion-control modes.

Reference image URLs for reference-to-video mode. Up to 9 on most models; `video.seedance_2_5` accepts up to 30, and the `video.wan_3*` tiers and both Gemini Omni Flash tiers accept up to 10 (see `limits.max_reference_images` on GET /models).

Wan 3.0 only (`video.wan_3`, `video.wan_3_prime`). URL of a document to base the video on — the model reads it and builds the shot from its contents. Selects reference-to-video on its own, and turns on Wan's reasoning pass automatically. Sending it to any other model returns 400 `unsupported_source_url`.

Wan 3.0 only (`video.wan_3`, `video.wan_3_prime`). URL of a PUBLIC webpage to base the video on — pages behind a login cannot be read. Selects reference-to-video on its own, and turns on Wan's reasoning pass automatically. Sending it to any other model returns 400 `unsupported_source_url`.

Seedance, Hailuo 03, Wan 3.0 and Gemini Omni Flash 1.1 only (3 on `video.gemini_omni_flash_v11`; the older `video.gemini_omni_flash` and `video.hailuo_03_max` accept none). Up to 3 reference clips on `video.hailuo_03` and the `video.seedance_2_0*` models (cited as `Video 1`…); up to 10 on `video.seedance_2_5` (cited as `@Video1`…); up to 5 on `video.wan_3` / `video.wan_3_prime`, 15s TOTAL across the pool and at least 16 fps each (cited as `Video 1`…). Each clip is roughly 2–30s.

Seedance, Hailuo 03 and Wan 3.0 only. Up to 3 reference audio clips on `video.hailuo_03` and the `video.seedance_2_0*` models, up to 10 on `video.seedance_2_5`, up to 5 (15s total) on `video.wan_3` / `video.wan_3_prime`. Cite them positionally in the prompt (`Audio 1` on Hailuo 03, `@Audio1` on Seedance) — this is how you give an on-camera character a consistent voice ("the woman in Image 1 speaks with the voice in Audio 1"). Cannot be the only reference: pair it with at least one reference image or video.

First-frame image for first-last-frame interpolation. Must be paired with last_frame_url.

Last-frame image for first-last-frame interpolation. Must be paired with first_frame_url.

Whether to include generated audio when supported.

Default: true

Output encoding bitrate for Seedance 2.0 Standard/Fast: `standard` or `high`. `high` requests a larger, higher-quality encode at no extra credit cost. Ignored by Seedance 2.0 Mini and by Seedance 2.5 (neither schema has the field).

Default: standard

Kling O3 only. Up to 3 structured elements (characters/objects), referenced in the prompt as `@Element1`, `@Element2`, `@Element3`. Passing elements selects the reference-to-video endpoint. Each element is an object: `{ frontal_image_url: string (main view), reference_image_urls?: string[] (1–3 extra angles), video_url?: string (a 3–10s driving clip — at most ONE element may carry a video), voice_id?: string (from POST /videos/voices) }`. Each element must have a frontal_image_url OR a video_url.

Kling O3 only. Multi-shot sequence: an array of `{ prompt: string, duration?: string ("1"–"15" seconds) }`. When provided it replaces the top-level `prompt` for shot structure.

Kling O3 only. Multi-shot structure: `customize` (you define shots) or `intelligent` (the model decides). Default `customize`.

Kling O3 reference-to-video only. Image to use as the first frame of the generated video.

File this generation's output into one of your PROJECTS (`GET /v1/projects`) the moment the run completes — the same thing the Video Studio does when you have that project open. Access is checked before the run is created, so an unknown id or one you cannot edit is a 404 `project_not_found` / 403 `project_forbidden` at request time rather than a silently unfiled result. Filing itself is best-effort and never fails a run you have already paid for. The run echoes it back as `project_id`.

Bill this generation to a WORKSPACE (team) credit pool instead of your balance (`GET /v1/teams`). Membership and a spending role are asserted before the run is created — 404 `invalid_team_id` when you are not a member, 403 `team_role_cannot_spend` when your role cannot spend. Requires the `teams:read` scope. The run echoes it back as `team_id`.

Optional id of a Marketing Studio ad template (`GET /v1/marketing/templates`). Composes the request server-side from the template RECIPE: the recipe prompt has its `{{product}}` / `{{avatar}}` tokens replaced with the positions your slot media is actually sent in, the slot media is emitted in the recipe's own `slot_order` AHEAD of any brand/moodboard references, and the template's model, aspect ratio, resolution and duration are applied unless you pass your own. Fill the fields the template lists under `recipe.required_inputs`; a missing one → 400 `marketing_slot_missing`. Passing a template for the other media type → 400 `marketing_template_mode_mismatch`. Unknown id → 404 `marketing_template_not_found`. A template whose model has no /v1 alias → 400 `template_model_unavailable` (pass an explicit `model` to run it anyway). A `prompt` you send alongside is ADDITIVE — it says what to CHANGE, so do NOT re-send the recipe prompt.

Optional GENRE (`GET /v1/marketing/formats`) — unboxing, tutorial, before-after, star review, comparison and so on. Fragments compose in the order genre → hook → setting, so the genre defines the piece, the hook claims its opening beat, and the setting relocates whatever those produced. WITH `marketing_template_id` the recipe is the base and the three fragments follow it, with your own `prompt` last as a change note. WITHOUT a template your `prompt` IS the base subject description and the fragments are directives applied to it, so they follow your prompt instead. Works WITHOUT a template. Unknown id → 400 `invalid_marketing_format_id`; a genre that does not apply to this media type → 400 `format_mode_mismatch`.

Optional OPENING MECHANIC (`GET /v1/marketing/hooks`) — a physical event in the first two seconds, not a copy angle: the product flying at the creator, an indoor blizzard, the camera being knocked, a held silence. `stunt` or `subtle`. Independent of the format, so any hook can open any genre. Works WITHOUT a template. Unknown id → 400 `invalid_marketing_hook_id`; a hook that does not apply to this media type → 400 `hook_mode_mismatch`.

Optional ENVIRONMENT (`GET /v1/marketing/settings`) — `realistic` (marble kitchen, gym floor, golden hour) or `unrealistic` (airplane wing, volcano rim, shrunk to doll size). Written as a relocation directive so it overrides the scene a template describes. Works without a template. Unknown id → 400 `invalid_marketing_setting_id`.

Fills the template's PRODUCT slot. Takes precedence over `product_id`.

Fills the template's AVATAR slot — who appears in the ad. Takes precedence over `avatar_id`. Rejected with 400 `avatar_not_supported_by_template` on a start-frame video template, which animates the product photo itself and has no avatar slot.

Fills the PRODUCT slot from your stored brand products (`GET /v1/marketing/products`) — no re-upload. Unknown or imageless id → 400 `invalid_product_id`.

Fills the AVATAR slot from your trained influencers or the house avatar library (`GET /v1/marketing/avatars`). Accepts the prefixed id (`influencer:abc`, `preset:xyz`), a bare influencer id, or an @handle. Unknown id → 400 `invalid_avatar_id`.

Last frame the clip lands on, paired with `image_url` for image-to-video. Supported by every model whose `capabilities.endFrame` is true at GET /v1/models — the Seedance, Kling V3/O3/2.6, and Hailuo 03/02 families. Sending it to any other model, or in a mode other than image-to-video (Kling O3 reference excepted), returns a 400 rather than silently dropping the input.

URL of the voice sample. `.mp3/.wav` audio or `.mp4/.mov` video, 5–30 seconds, clean single-voice audio.

Absolute URL of the source image.

File this generation's output into one of your PROJECTS (`GET /v1/projects`) when the run completes. Access is checked before the run is created; filing itself is best-effort.

Absolute URL of the source video.

`video_upscale.fal_video_upscaler` (Topaz) or `video_upscale.flux_video_upscale` (Flux).

Default: video_upscale.fal_video_upscaler

Topaz: 2 or 4. Flux: any value from 1.5 to 3.

Default: 2

Flux only. `precise` keeps the source faithful; `creative` adds detail.

Default: creative

Flux only, optional. Guides the creative pass.

Absolute URL of the source image.

Either 2 or 4.

Default: 2

Scenes in playback order, 1-60. Each: `url` (absolute https), `kind` ("video" default | "image"), `audio_url` (THIS scene's voiceover), `audio_mode` ("replace" default | "mix" to keep the clip's own sound ducked underneath), `hold_last_frame` (default true), `duration_sec` (image only — defaults to its own audio's length, else 5s), `trim_in_sec`, `trim_out_sec`, `transition_ms` (crossfade INTO this clip; 0 = hard cut), `motion` + `motion_intensity` (image Ken-Burns), `mute_audio`.

Up to 32 tracks placed at absolute positions on the finished timeline. Each: `url`, `start_sec` (default 0), `volume` (0-1, default 1), `loop` (repeat until the video ends — for a music bed), `fade_in_sec`, `fade_out_sec` (relative to the track's own start/end, not the timeline).

"16:9" (default), "9:16", "1:1", "4:5" or "21:9". Every clip is scaled/cropped to it.

Default: 16:9

"cover" (default) crops clips to fill the frame; "contain" letterboxes them.

Default: cover

Default crossfade for clips that name none. 0 = hard cuts throughout.

Default: 0

Duck EVERY clip's own source audio to this level (0-1) so the tracks sit on top. 0 silences the clips entirely.

{ preset_id, position?, animation?, words_per_line? } — burn captions onto the finished cut, transcribed from its own audio. Preset ids come from `GET /v1/faceless-reels/caption-presets`. Free, and cosmetic: a caption failure ships the uncaptioned render rather than failing the compose.

File the finished video into one of your PROJECTS (`GET /v1/projects`) when the compose completes.

Title for the finished video in your library.

Absolute URL to the source video.

Absolute URL to the source audio.

Base64-encoded audio content. Provide this instead of `audio_url` when uploading audio inline.

Optional file name to associate with inline audio.

Optional title used for the internal video record.

Default: AI Lip-sync Video

Optional description for the internal video record.

How the video should align to the audio.

Default: cut_off

Optional lipsync model alias from `/models`.

Default: lipsync.lipsync_2_pro

Optional duration hint between 1 and 300 seconds.

File this generation's output into one of your PROJECTS (`GET /v1/projects`) when the run completes. Access is checked before the run is created; filing itself is best-effort.

The text to speak. For `speech.seed_audio_1_0` this is a free-form audio prompt (max 2048 chars) that can also describe scenes/dialogue and reference audio inputs as @Audio1–@Audio3.

The voice id to use: either a stock ElevenLabs voice id or one of your cloned voice ids (`fal_cloned_<id>`). List options via `/audio/voices`. Required for ElevenLabs models. For `speech.seed_audio_1_0` it is OPTIONAL and takes a Seed preset name (e.g. `vivi_mixed_en_zh_ja_es_id`) instead.

Optional speech model alias from `/models`.

Default: speech.elevenlabs_turbo_v2_5

Optional human-readable voice name passed through to the audio generator.

Optional output format when supported by the backing provider. For `speech.seed_audio_1_0`: one of `wav`, `mp3`, `pcm`, `ogg_opus` (default `mp3`).

Seed Audio 1.0 only — up to 3 reference audio URLs (each ≤30s / 10MB), referenced in the prompt as @Audio1–@Audio3. Cannot be combined with `image_url`.

Seed Audio 1.0 only — a single reference image URL (jpeg/png/webp ≤10MB). Cannot be combined with `audio_urls`.

Seed Audio 1.0 only — output sample rate in Hz: 8000, 16000, 24000 (default), 32000, 44100 or 48000.

Seed Audio 1.0 only — speech speed 0.5–2 (1 = normal).

Seed Audio 1.0 only — volume 0.5–2 (1 = normal).

Seed Audio 1.0 only — pitch shift in semitones, -12 to 12 (0 = normal).

Description of the music you want generated. Required unless `composition_plan` is provided; the two cannot be combined.

Structured composition plan instead of a prompt (ElevenLabs only). music_v1 shape: `{ positive_global_styles[], negative_global_styles[], sections[] }` with per-section styles, duration_ms (3000-120000) and lyric lines. music_v2 shape: `{ chunks[] }` where each chunk has `text` (may carry [Section] and {direction} markup), `duration_ms`, `positive_styles[]` and optional audio-conditioning refs. Duration and billing derive from the plan's summed durations.

Optional music model alias from `/models`. A chunks-shaped `composition_plan` implies `music.elevenlabs_music_v2`.

Default: music.elevenlabs_music_v1

Desired music length in seconds. ElevenLabs prompt mode: 3-600 (default 30; ignored with `composition_plan`). MiniMax Music 3: an upper bound of 1-300 (default 60) that billing is charged on — the model may finish earlier. Lyria 3 Pro ignores it and produces a flat-length song.

Default: 30

The lyrics to sing. REQUIRED for `music.minimax_music_3` — that model writes none of its own. Structure tags ([intro], [verse], [pre-chorus], [chorus], [post-chorus], [bridge], [instrumental], [solo], [outro]) must each be on their own line; Genfire splits a tag off a shared line for you so no lyric is silently dropped. Ignored by ElevenLabs (use `composition_plan`) and Lyria 3 Pro (it writes its own).

MiniMax Music 3 only: flow-matching Euler steps per 8-second chunk, 1-100. Higher is better quality and slower.

Default: 30

MiniMax Music 3 only: classifier-free guidance scale of the flow-matching stage, 0-20. Higher follows the prompt more literally.

Default: 1.7

Return detailed music metadata when supported (ElevenLabs only).

Default: false

Include timestamps when `include_details` is true (ElevenLabs only).

Default: false

Guarantee instrumental output (ElevenLabs prompt mode only).

With a music_v1 `composition_plan`: enforce section durations exactly instead of letting the model flex them (music_v2 always enforces them).

Default: true

Random seed for reproducible results (ElevenLabs `composition_plan` mode, or MiniMax Music 3). The seed actually used is returned in the run output.

Optional image URL used as inspiration for the generated music. Lyria 3 Pro only — the model matches the mood and theme of the image.

Deprecated — no current music model supports negative prompting (Lyria 3 rejects it, MiniMax Music 3 has no such field); the field is ignored.

Optional output format when supported by the backing provider (ElevenLabs default `auto` picks the best mp3 for the model).

The sound effect prompt.

Optional sound effect model alias from `/models`.

Default: sfx.elevenlabs_v1

Optional desired duration in seconds.

Optional output format when supported by the backing provider.

Optional prompt influence value when supported.

Whether to generate a loop-friendly result when supported.

URL of a direct audio file (mp3, wav, m4a, aac, ogg, flac, opus, webm, wma). One of audio_url / video_url / youtube_url is required.

URL of a direct video file; audio is extracted before transcription.

A YouTube URL to download and transcribe (max 2 hours).

Optional transcription model alias from `/models`.

Default: transcription.whisper_v1

A public product page URL. Private, local, and unsafe targets are blocked.

A workflow id such as `hook_pack` or `creative_pack`.

A workflow id such as `hook_pack`, `ugc_ad`, or `creative_pack`.

Use the schema from `GET /workflows/{workflowKey}` or the workflow catalog below.

A workflow id from `GET /user-workflows`.

Which page of the workflow to run. Defaults to the first page.

Node ids to run — their upstream dependencies run automatically. Defaults to the editor behavior: the page’s Export nodes if it has any, otherwise every generation leaf node (image/video/audio/text nodes with no outgoing edges).

Per-run parameter overrides shaped as `{ nodeId: { paramKey: value } }`. Values must be primitives (string, number, boolean, or null) and the object must serialize to at most 50KB. Overrides apply to this run only — the stored workflow is never modified.

A workflow id from `GET /user-workflows`.

The run id returned by `POST /user-workflows/{workflowId}/runs`.

Optional status filter such as `queued`, `processing`, `completed`, `failed`, or `partial`.

Optional batch mode filter: `workflow` or `operation`.

Optional target filter such as `hook_pack` or `images.generations.create`.

Maximum number of batches to return.

Default: 25

The batch id returned by `POST /batches`.

The batch id returned by `POST /batches`.

Use `workflow` for workflow batches or `operation` for supported primitive operations.

Workflow key or supported operation target such as `images.generations.create`.

How many items to process concurrently.

Default: 2

Array of batch items. Each item must have an `input` object.

Optional webhook endpoint id to filter deliveries.

Maximum number of deliveries to return.

Default: 25

Public HTTPS endpoint that will receive webhook POST requests.

Optional human-readable label for the endpoint.

Optional list of event types to subscribe to.

Default: ["run.completed","run.failed"]

The webhook delivery id.

The webhook endpoint id.

New destination URL.

New description or `null` to clear it.

Use `active` or `disabled`.

Replacement list of subscribed event types.

The webhook endpoint id.

An authored book: `{ title, cast:[{name, description}], places?:[{name, description}], pages:[{ text, visual, cast?, place?, kind? }] }`. Rendered exactly as written — no planner runs. `kind` is `page` | `spread` (one picture across two facing pages, one render, one page credit, must start on an even slot) | `text-page` (words only, free). Overrides `idea`/`script`/`pages`.

One line to write the story from, when you are not supplying `plan` or `script`.

Your full story text (≤ 20000 chars). Split across pages by the planner; the words themselves are never rewritten.

Book title. Defaults to the planner’s.

Up to 4 characters as `{name, description}` — one fixed physical description each, which becomes that character’s reference sheet.

`board` | `picture` (default) | `early-reader`. Sets the word budget and the page-count options.

Interior page count within the band’s options (board 12/16/20, picture 16/24/32/40, early-reader 24/32/40/48).

Art style from `GET /v1/picture-books/styles`. Defaults to `storybook`.

Trim/aspect preset (KDP trims, other print sizes, or digital aspects). Defaults to `kdp-8.5x8.5`.

`low` (default) or `medium`. Medium costs several times more per unit — confirm before choosing it.

`typeset` (default) — Genfire sets the words in post, so they stay editable and correctly spelled — or `lettered`, where the model paints them into the art. The FRONT COVER is always lettered.

Bill the team pool (requires a billable role on that team).

Same body as the generation call — `idea`, `script` or `plan`, plus the config fields.

Sets the page-count options and the word budget.

Interior page count.

`low` or `medium`.

The subject / seed for the reel. Use a phrase like "the disappearance of the Sodder children" or "Surprise me with a fresh idea".

Niche preset id from `GET /v1/faceless-reels/presets` (drives topic + tone). Defaults to a creepy-story preset.

Visual style id from `GET /v1/faceless-reels/styles`. Defaults to the preset’s recommended style.

Target length in seconds (10–600, up to 10 minutes). Drives script + scene count. Defaults to the niche’s natural length.

Caption font/animation preset from `GET /v1/faceless-reels/caption-presets`.

Default: hormozi

Override the caption animation (highlight | pop | typewriter | classic | background).

Vertical caption placement: "top" | "middle" | "bottom". Default middle (the classic centered render).

Default: middle

TTS voice id (ElevenLabs or Qwen). Defaults to a built-in narrator voice.

Camera-motion feel for the image slideshow: "auto" (per-niche, default) | "calm" (slow pans, subtle zoom) | "dynamic" (mixed pans + zooms) | "energetic" (corner punch-ins + shake).

Default: auto

How much of the reel is real video: "stills" (Ken-Burns slideshow, default) | "hook" (premium — the FIRST scene is a real omni image-to-video clip) | "full" (ultra — EVERY scene is a real omni clip, one i2v clip cost per scene). Wins over animated_hook.

Default: stills

LEGACY: true ≈ animation_mode "hook". Prefer animation_mode.

Default: false

i2v model for animated clips. Every value resolves to "omni" (gemini-omni-flash); "grok"/"seedance-mini" are accepted legacy aliases.

Default: omni

Extra creative direction passed to the script model.

{ prompt, scene_hint? } to author a fully custom story instead of using a niche preset.

Background music: { source: "none"|"preset"|"ai"|"library", preset_id?, prompt?, track_id? }.

Niche preset id (affects default scene count).

Target length in seconds (10–600, up to 10 minutes).

Music config; only `source: "ai"` adds a music fee.

The channel name.

CHANNEL identity: square avatar image URL.

CHANNEL identity: one-line pitch shown under the channel name.

CHANNEL identity: longer channel description.

CHANNEL identity: niche id (education, history, kids, storytelling, true-crime, finance, motivation, science, mystery, horror, animals, mythology, psychology).

CHANNEL identity: "shorts" (9:16 reels) or "longform" (16:9 explainer episodes) — picks which engine renders each episode.

Default: shorts

CHANNEL identity: defaults every new episode inherits — { aspect_ratio: "16:9"|"9:16", target_duration_sec: 8-600, motion_style: "seamless"|"scenes"|"stills" }.

Niche preset id.

Visual style id.

Caption preset id.

Vertical caption placement: "top" | "middle" | "bottom".

Default: middle

TTS voice id.

Camera-motion feel: "auto" | "calm" | "dynamic" | "energetic".

Default: auto

Animation tier: "stills" | "hook" (first scene animated) | "full" (every scene a real omni clip).

Default: stills

LEGACY: true ≈ animation_mode "hook".

Default: false

i2v model for animated clips (every value resolves to "omni").

Default: omni

Target length (10–600, up to 10 minutes).

Background music config.

"ai-auto" (fresh ideas) or "user-list" (rotate `topic_seeds`).

Default: ai-auto

Topics to rotate through when `topic_source` is "user-list".

Reels per day (1–6).

Default: 1

Local "HH:mm" times; length must equal `cadence_per_day`.

Default: ["18:00"]

IANA timezone for the slots.

Default: America/New_York

STANDING creative direction every episode inherits — tone, pacing, what to avoid.

{ prompt, scene_hint? } — a fixed recurring premise every episode is written from.

The channel’s RECURRING CAST: [{ url, label }] up to 8 https images every episode inherits.

A reference channel this one is modelled on.

highlight | pop | typewriter | classic | background.

Caption line length (1-12).

Episode titles queued for this channel (up to 24).

Connected accounts every finished episode AUTO-PUBLISHES to, as "platform:account_id" (see GET /social/accounts). Omit to keep episodes private.

Whether the schedule is active.

Default: true

Subscription id.

Subscription id.

Channel id.

Episode title or subject.

"16:9" | "9:16". Overrides the channel default; 16:9 forces the explainer engine.

Explainer 20-600, reel 10-120. Clamped to the winning engine.

"seamless" | "scenes" | "stills".

Channel id.

1-100, default 30.

Channel id.

Episode title or subject.

"16:9" | "9:16".

Explainer 20-600, reel 10-120.

"seamless" chains each beat off the last frame within a sequence; "scenes" is one shot per beat; "stills" is no motion.

Override the channel style for this episode.

Override the channel narrator for this episode.

[{ url, label }] up to 8 — added on top of the channel’s recurring cast.

Your own narration instead of the writer’s. Forces the explainer engine and sets the runtime.

Describe the look instead of picking a style_id.

An image that becomes frame 0 (the style anchor). Not a reference image.

Burn captions. Default: on for shorts, off for long-form.

{ source: none|preset|ai|library, preset_id?, prompt?, track_id? }.

"reel" | "explainer" — force the engine instead of deriving it.

Subscription id.

Optional topic override for this run; otherwise resolved from the subscription.

The full standing brief the run executes.

Short name for the schedule list.

once | daily | weekly | monthly.

Default: daily

Local start on a 24-HOUR clock, "HH:mm" — 3:40pm is "15:40". Requires timezone.

IANA zone for `time`, e.g. "America/New_York".

Alternative to time+timezone: an ISO 8601 instant with offset. Must be in the future.

Credit ceiling ONE run may spend (1-2000).

Default: 100

Autopilot — runs publish within budget instead of waiting for the owner’s sign-off.

Default: false

AI Employee to run the task as.

{ email, slack } — where a finished run reports. Both default false.

false pauses, true resumes (also clears an automatic failure pause).

{ email, slack } — only the channels you name change.

What the explainer is about. Also used as the video title. Required even with a `script` (labels the run + video).

Structured agent-authored script: { cast?: [{ name, description }] (≤3, UPPERCASE names, one fixed visual identity each), beats: [{ narration (spoken words, may carry ElevenLabs v3 [audio tags]), visual (concrete storyboard shot-spec with quoted on-screen labels), motion? (camera/animation director note), render? ("anchored"|"direct"), continues? (bool — continue previous shot via last-frame chaining; prefer true on most beats so the film flows as continuous footage, breaking only at deliberate scene changes; never where a cast member enters/returns — their introduction needs an anchored shot), refs? ([1-based reference_images indices]), emphasis? (≤3 verbatim narration substrings for keyword captions), cast? ([declared names]) }] (3–100 beats). Bypasses EVERY internal LLM call; narration length sets the duration (target_duration_sec is ignored). Validation errors return 400 `invalid_script` with the exact fix.

Plain word-for-word narration (no beat structure). Genfire still storyboards the visuals for you. Ignored when `script` is present.

Authored scripts (`script` / `custom_script`) that re-tell an episode this account already rendered are refused with 409 duplicate_script (the match is named). Pass true to render anyway.

Default: false

Visual style preset from `GET /v1/explainers/styles` (41 looks: pixel-art, claymation, whiteboard-doodle…). Defaults to a 2D-illustration look.

"16:9" (default) or "9:16".

Default: 16:9

Target runtime in seconds (20–600). Ignored when `script` is present — the narration length sets the duration.

Default: 60

Narration voice id (ElevenLabs; renders on eleven_v3 with expressive [audio tags]). Defaults to a documentary narrator.

How many scenes render as real omni video clips: "full" (every scene, default) | "mixed" (every 5th) | "stills" (Ken-Burns only, cheapest). Draft-run lever for agents.

Default: full

How animated scenes join: "seamless" (default — each clip seeds from the previous clip's last frame; continuous footage) | "cuts" (every scene is its own shot, hard cuts — "scene by scene"). Stills ignore it.

Default: seamless

Background music bed: { source: "none"|"preset"|"ai"|"library", preset_id?, prompt?, track_id? }.

Captions are OPT-IN — omit for none. Any caption preset id from `GET /v1/faceless-reels/caption-presets` enables burned captions.

Default: none

Vertical caption placement: "top" | "middle" | "bottom" (default when captions are on).

"full" burns the transcript; "keywords" pops only each beat's emphasis words at their spoken timestamps.

Default: full

Override the caption animation (highlight | pop | typewriter | classic | background).

Up to 8 { url (https), label? (≤60 chars) } — products/characters/brands that must appear. Beats reference them via `refs` (1-based); those scenes render via omni reference-to-video. Put `refs: [1]` on the FIRST beat — the opening frame is generated as an image EDIT from the refs, locking the subject's real identity into the style anchor every later scene inherits.

Target runtime in seconds (20–600). Ignored when `script` is present.

Structured script (same shape as generate) — the quote derives from its narration length.

"full" | "mixed" | "stills" — how many scenes render as real video clips (the dominant cost lever).

Default: full

Music config; only `source: "ai"` adds a music fee.

Narration voice (a Seed Audio preset switches the TTS credit key).

"16:9" | "9:16" (no cost impact today; accepted for parity).

The creative concept / narrative direction for the video (e.g. "a lonely astronaut drifting through neon ruins, longing for home"). Steers the shot-list and styling.

https URL of the song to score the video to. Provide THIS or an inline `song` (not both). Optionally pair with `song_title`, `song_lyrics`, `song_sections`, `song_word_timestamps`.

Inline song generation (instead of `song_url`): { prompt (what the track should sound like), duration_ms (10000–600000), instrumental? }. Genfire generates the track first via ElevenLabs music_v2 with word timestamps, bills it separately, then produces the video.

Title for a bring-your-own `song_url` track (labels the output). Ignored with an inline `song`.

Full lyrics for a bring-your-own track — improves lyric-aware pacing and captions.

Optional pre-computed sections for a bring-your-own track: [{ label, start_sec, end_sec }]. Skips section analysis.

Optional word timings for karaoke captions on a bring-your-own track: [{ word, start_sec, end_sec }].

For a bring-your-own `song_url` only: transcribe the track to derive lyrics + word timestamps (unlocks lyric_captions and lyric-aware scenes). Runs as its own step, billed per second (Whisper). No-op when `song_word_timestamps` were supplied or an inline `song` is used (those get timings natively); an instrumental track proceeds without lyrics. Default false.

Default: false

Visual style preset id from `GET /v1/music-videos/styles` (cinematic-performance, anime, neon-city…).

"9:16" (default) or "16:9".

Default: 9:16

How many scenes the song is cut into: "low" (~10s/scene) | "medium" (~7s) | "high" (~5s). More scenes = more clips = higher cost.

Default: medium

Burn karaoke-style lyric captions (uses word timestamps from the song). Default false.

Default: false

Up to 8 { url (https), label? (≤60 chars) } — characters/products/looks that should appear and anchor the style.

Length of the song in seconds (the dominant driver of scene count).

"9:16" (default) or "16:9".

Default: 9:16

"low" | "medium" | "high" — scenes per second of song (the main cost lever).

Default: medium

Whether karaoke lyric captions are burned in (no material cost impact today; accepted for parity).

Default: false