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, required unless marketing_template_id selects it.

Use the same template and product/avatar inputs as generation. Applies its defaults before quoting.

Product reference matching the generation request.

Creator reference matching the generation request.

Stored product matching the generation request.

Stored avatar matching the generation request.

Video task: reference, editing or extension. Source-driven editing measures the source clip server-side.

Source video URL or owned run reference for editing. Must be the same value the generation request sends.

Reference clips. Presence affects model routing and rates; source-driven edits measure their duration.

Per-clip windows over reference_video_urls (`[{ index | url, start, end | duration }]`), as sent to generation. Reference edits bill the trimmed pool.

Image references matching generation.

Audio references matching generation.

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

Video duration in seconds (also used for lipsync audio when no audio_url). Send it (and `aspect_ratio`, `follow_source`, `keep_source_audio`) exactly as the generation request does: on `video.seedance_2_5` with one reference clip, task `reference` (or none) and the ratio omitted, `auto` or the clip's own, an omitted (or `auto`) duration is priced on the clip's measured length — the length that run renders and bills.

Whether audio is generated (affects some video models).

Video aspect ratio, exactly as the generation request sends it. On a one-clip `video.seedance_2_5` reference run it decides whether an omitted duration follows the clip (ratio omitted, `auto` or the clip's own) or is 5s — so it can change the price.

Genjudo (`video.seedance_2_5`), exactly as the generation request sends it.

Genjudo (`video.seedance_2_5`), exactly as the generation request sends it: replaces `duration` with the clip's own measured length.

Number of outputs (video/image). `video.seedance_2_5` renders one video per request — a count above 1 is clamped to 1 and quoted as one video.

Image quality tier — GPT Image 2 / GPT Image 2.5 / Genfire (low/medium/high), Ideogram 4.5 (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).

Video: the trained models the generation will run with (`[{ id, scale? }]`, up to 3). Moves the quote onto the Hailuo 03 LoRA rate — `video.hailuo_03` only; any other model returns 400 `invalid_loras`. Training itself is quoted by POST /v1/loras/estimate-cost.

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

With `include=stock`: free-text search over the stock catalog (name, description, labels).

With `include=stock`: filter stock voices by gender label (e.g. `male`, `female`, `neutral`).

With `include=stock`: filter by age label (`young`, `middle_aged`, `old`).

With `include=stock`: filter by accent label (e.g. `american`, `british`, `australian`).

With `include=stock`: ISO 639-1 language the voice is verified for (e.g. `es`).

With `include=stock`: filter by use-case label (e.g. `narration`, `conversational`, `characters`).

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

Report the WORKSPACE pool's spend instead of your own (`GET /v1/teams`). Requires the `teams:read` scope; 404 `invalid_team_id` when you are not a member. Same date-range semantics.

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

Declared file size. Optional, and rejected if greater than the 5 GB ceiling — except with `resumable: true`, where it is REQUIRED, a whole number of bytes, at most 104857600 (100 MiB), and pinned into the session as the object's exact length.

Also open a resumable upload session (`upload_session_url`) for chunked uploads. Requires `size_bytes`. Default false.

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. REQUIRED with `photo_urls` or `appearance`; OPTIONAL with `recipe`, where a blank handle is derived from the recipe (e.g. `retro_beehive`, suffixed `_2`, `_3`… until free).

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

BUILDER mode. The Influencer Studio trait recipe: `tier` (required — `average`, `bold` or `extreme`), `species` (optional — `mantis`, `ant` or `dog` for a creature; omit for a human), `selection` (required — an object of section key → up to 4 option keys, at most 18 sections, keys `[a-z_]`, options `[a-z0-9_]`, e.g. `{ "hairstyle": ["beehive"] }`), `brief` (optional, ≤4000 chars). Stored on the character as `builder_recipe` for Recreate. Requires `prompt`; cannot be combined with `photo_urls` or `appearance`.

BUILDER mode, required there: the casting prompt the sheet renders from (≤4000 chars), composed from the recipe. Only the sheet render reads it — it is never appended to later @mention generations.

BUILDER mode, optional: ONE face photo (absolute https URL, e.g. an `asset_url` from POST /v1/uploads). The sheet restyles this person instead of inventing one, and is priced as an edit.

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.

The page to capture, e.g. `https://example.com`. A bare domain is accepted (https is assumed).

Up to 4 entries of `{ "name": "desktop", "width": 1440, "height": 900, "mobile": false }`. Width 200–2560, height 200–20000; `mobile: true` emulates a phone (touch + mobile UA), not just a narrow window. Names are slugged and must be unique — they name the shot in the output.

Default: desktop 1440x900 and mobile 390x844

Capture the whole scrollable page instead of the viewport box. Clipped at 8000 CSS pixels so an infinite-scroll page cannot produce an unbounded image.

Default: false

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 set to build, the change to make, or the camera move to key. Up to 4000 characters.

`blockout`, `reblock` or `camera`.

Default: blockout

Optional context from the open file: `summary`, `objects[]` ({name, location, dimensions, primitive}), `bounds` ({min, max}), `camera` ({name, location, rotation_deg, lens_mm}), `frame_start`, `frame_end`, `fps`, `cursor`.

Required for `reblock`: the `spec` a previous call returned (with any edits the host made).

Soft cap on primitives in a blockout (1–120).

Default: 60

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_1

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 / 2.5, Seedream, Qwen Image 2 and Nano Banana; Grok uses at most the first 3. `image.ideogram_v4_5` reads the first image as the SOURCE to edit and up to 4 more as references (3 when `mask_url` is sent); any beyond that are ignored. 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.gpt_image_25_flare, image.gpt_image_25_sunburst, image.genfire_v1, image.nano_banana_2, image.nano_banana_2_1, image.nano_banana_pro, image.ideogram_v4_5, image.z_image_turbo, image.z_image_tiling); any other model returns 400 `model_lacks_mask_support` rather than silently ignoring the mask and billing a full-frame rewrite. White = repaint on EVERY model: Ideogram's own API reads masks the other way round, and Genfire inverts yours server-side, so never pre-invert one. 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`).

Z-Image image-to-image only (`image.z_image_turbo`, `image.z_image_tiling` with `image_url`): how far the result may move from the source, 0-1 (default 0.6; inpaint defaults to 1). Z-Image image-to-image is NOT instruction editing — the prompt describes the whole result. Any other model returns 400 `strength_unsupported`.

`image.z_image_base` only: what to steer away from. Turbo is guidance-distilled and cannot read one; any other model returns 400 `negative_prompt_unsupported`.

`image.z_image_controlnet` only: what is extracted from `image_url` to guide structure — `canny` (edges, default), `depth`, `pose`, or `none` when the image is already a control map. `image_url` is required on this model (400 `control_image_required`).

`image.z_image_controlnet` only: how tightly the result follows the control image, 0-1 (default 0.75).

`image.z_image_tiling` only: which edges wrap seamlessly — `both` (default), `horizontal` or `vertical`.

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.gpt_image_25_sunburst / image.gpt_image_25_flare / 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. image.ideogram_v4_5: low, medium or high (no auto), each its own base rate; 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). image.nano_banana_2, image.nano_banana_2_1 and image.nano_banana_pro accept it on BOTH paths. Affects cost: 1K=1×, 2K=1.5×, 4K=3× — except image.ideogram_v4_5, which takes 1K or 2K (default 2K) at the SAME price and rejects 4K; its masked and Precise (`edit_precision: high`) edits keep the source image's size.

`image.ideogram_v4_5` edits only: `regular` (default) or `high` — Precise Edit, which restores every pixel the edit did not change instead of re-rendering the whole frame. Same price as a regular edit. Requires `image_url` (or `image_urls`) — without one it is 400 `edit_precision_requires_source_image`; on any other model it is 400 `edit_precision_unsupported` rather than silently ignored; any other value is 400 `invalid_request`.

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

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

The video prompt. Three exceptions: `video.hailuo_03_max_3d` (H3 Max 3D to Video), where it is optional scene intent (≤2,000 characters) — omit it or send an empty string and the 3D render alone drives the clip; `video.hailuo_03_max_insert` (H3 Max Insert), where it describes the NEW scene and may be omitted when `reference_image_urls` / `reference_video_urls` guide it instead — with neither it is 400 `insert_guidance_required`; and `video.hailuo_03_max_recast` (H3 Max Recast), where it is optional (≤2,000 characters) and only says who becomes whom, or what else to keep — the cast photos alone are enough.

Optional video model alias from `/models`.

Default: video.veo_3_1

Video aspect ratio. Omitted, it is 16:9 — with one exception: `video.seedance_2_5` with EXACTLY ONE `reference_video_urls` clip and `task` `reference` (or omitted) or `editing` follows the clip (`auto`). Send a ratio to override it — on a one-clip `reference` run a ratio other than `auto` or the clip's own also stops the LENGTH following the clip (an omitted duration is then 5s).

Default: 16:9

Target duration in seconds. Omitted, it is 5. On `video.seedance_2_5`, `"auto"` means the same as omitting it — never a length the model picks: with EXACTLY ONE `reference_video_urls` clip, `task` `reference` (or omitted) and `aspect_ratio` omitted, `auto` or the clip's own ratio, the run follows the clip's own length (the trimmed window when trimmed) — whole seconds, rounded UP, 4–30 — and bills on that length, as an edit does; in every other case it is 5s. Send a number to override it.

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. REQUIRED on `video.hailuo_03_max_extend` (the clip to continue, 1.625-60s, ≤50 MB), `video.hailuo_03_max_3d` (the 3D render, ≤15s), `video.hailuo_03_max_insert` (the clip to cut into, ≤60s, ≤50 MB) and `video.hailuo_03_max_recast` (the clip to recast, 5-30s, no single shot over 15s) — 400 `source_video_url_required` without it. All four are measured server-side before the run is created: a clip outside those bounds is 400 `source_video_too_short` / `source_video_too_long`, a clip over 50 MB (Extend / Insert; also `video.flux_3_edit`) is 400 `source_video_too_large`, and an unreadable 3D render or Recast source is 422 `source_video_unreadable` (its length is the price).

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). On `video.hailuo_03_max_recast` they are the CAST and REQUIRED: 1-4 photos, one per new person, mapped left to right onto the main people in `source_video_url` — none is 400 `reference_image_urls_required`, a 5th is 400 `invalid_reference_image_urls`. On `video.seedance_2_5` an `image_url` sent alongside any reference media (`reference_image_urls`, `reference_video_urls` or `reference_audio_urls`) is not animated as a start frame: it is appended AFTER these images and becomes the next `@ImageN` — cite it that way (only a pool already holding 30 images makes that a 400). To animate a frame, send `image_url` with no reference media.

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`, `video.hailuo_03_max_turbo` and `video.hailuo_03_max_styles` accept none). Up to 3 reference clips on `video.hailuo_03`, `video.hailuo_03_max` and the `video.seedance_2_0*` models (cited as `Video 1`…); up to 10 on `video.seedance_2_5` (cited as `@Video1`…; each 2–30s after any trim, 30s COMBINED across the pool, duplicate URLs de-duplicated; `task` `editing` and `extension` take EXACTLY ONE clip and an edit clip must be at least 4s); 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`…); up to 3 on `video.hailuo_03_max_insert`, where they guide the inserted scene — 15s TOTAL across the pool, measured server-side (400 `reference_video_pool_too_long` over it). Each clip is roughly 2–30s.

Optional per-clip TIME WINDOWS for `reference_video_urls` — "use seconds 3–8 of the second clip". Each entry is `{ index, start, end }` (or `{ url, start, end }`, or `duration` instead of `end`; seconds, `index` is 0-based into `reference_video_urls`). Only the window is sent to the model and — where clip length is billed — billed. Windows must fit the model's per-clip cap: 3s on `video.gemini_omni_flash_v11`, 15s on `video.hailuo_03*` and `video.wan_3*` (15s TOTAL across the Wan pool), 30s on Seedance; a longer window is a 400 `invalid_reference_video_trims`. The cut happens server-side with audio kept.

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` (each 2–30s and at most 15 MB, 30s COMBINED), 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. Exception: on `video.seedance_2_5` with EXACTLY ONE `reference_video_urls` clip and `task` `reference` (or omitted) or `editing`, sending neither `generate_audio` nor `keep_source_audio` keeps the CLIP'S OWN sound instead (`keep_source_audio` defaults to true there) — unless `reference_audio_urls` is sent or the clip has no audio track, where the soundtrack is generated as usual. Send `generate_audio: true` for a generated soundtrack, or `false` for silence.

Default: true

Output ENCODE quality: `standard` or `high`. `high` requests a larger, higher-quality file at no extra credit cost. Declared by `video.seedance_2_0` and `video.seedance_2_0_fast`; on every other model (`video.seedance_2_5`, `video.seedance_2_0_mini` and every non-Seedance model — `capabilities.bitrate_mode` is false) it has no effect and is ignored, whichever value you send. A value other than `standard` or `high` is 400 `invalid_bitrate_mode`. Filter on `capabilities.bitrate_mode` at GET /v1/models.

Default: standard

GENFIRE GENJUDO — `video.seedance_2_5` only (`capabilities.video_task` at GET /v1/models); any other model returns 400 `unsupported_task`. `reference` = MOTION TRANSFER: the clip in `reference_video_urls` supplies the motion, the images in `reference_image_urls` supply who performs it. With EXACTLY ONE clip it MATCHES THE CLIP by default: an omitted `aspect_ratio` is `auto`, an omitted (or `auto`) `duration` is the clip's own length (billed on the measured clip) unless you send a ratio other than `auto` or the clip's own, and with neither `generate_audio` nor `keep_source_audio` sent the clip's own sound is kept (not when `reference_audio_urls` is sent or the clip has no audio track) — send any of them to override. `editing` = VIDEO EDIT: the clip itself is re-lit / swapped / cleaned up, and the model coerces BOTH `aspect_ratio` and `duration` to auto (the output follows the source, so sending either is a no-op); the clip's own sound is kept by default the same way. `extension` = continue the clip past its last frame; `aspect_ratio` is coerced to auto, `duration` is yours (5s when omitted), no other default applies and `keep_source_audio` has no effect (ignored — the new seconds have no source sound). `editing` and `extension` take EXACTLY ONE `reference_video_urls` clip — none is 400 `task_requires_reference_video`, a second is a 400 too — and an edit clip must be at least 4s. Omit `task` for the model default (reference). Pre-written prompts for both modes: GET /v1/videos/genjudo/presets.

GENFIRE GENJUDO — `video.seedance_2_5` with a `reference_video_urls` clip, task `reference` (or omitted) or `editing`; ignored on `extension` (the new seconds have no source sound) and when no clip is sent. The clip is sent to the model SILENT and its own soundtrack (the same trim window) is laid back under the finished render, so the result keeps the original sound and no generated audio is written (`generate_audio` is forced false). DEFAULTS TO TRUE with exactly one clip when you send neither `keep_source_audio` nor `generate_audio` — except when `reference_audio_urls` is sent or the clip has no audio track; send `false` (or `generate_audio: true`) for a generated soundtrack instead. Any other model returns 400 `unsupported_genjudo_option`.

GENFIRE GENJUDO "Match the clip" — `video.seedance_2_5` task `reference` with a clip and `aspect_ratio` omitted, `auto` or the clip's own ratio: the output frame and length follow the clip, which lets a motion-transfer prompt that reads like an edit ("replace the person in @Video1…") run instead of being refused. An explicit `follow_source: true` REPLACES any `duration` you send with the clip's own length — whole seconds, rounded UP, 4–30 — and that is what bills; an `aspect_ratio` other than `auto` or the clip's own stops it following. A one-clip `reference` run that sends neither `aspect_ratio` nor `duration` already matches the clip without it. Dropped silently where it does not apply; any non-Genjudo model returns 400 `unsupported_genjudo_option`.

Default: false

Seedance 2.5 DRAFT — `video.seedance_2_5` only (`capabilities.draft` at GET /v1/models); any other model returns 400 `unsupported_draft` (Flux 3's draft is its own model, `video.flux_3_draft`). `true` renders a 480p PREVIEW billed at the 480p price — on text-, image- and reference-to-video, `task` included — and `resolution` is ignored (always 480p). Happy with it? `POST /v1/videos/generations/{id}/final` with the draft's run id re-renders the SAME shot (prompt, references, duration, aspect ratio, audio) as a native 1080p video, priced at what a direct 1080p render of this request costs; finals can be made for 7 days from the draft's creation, as many times as you like. Not a boolean → 400 `invalid_draft`; 503 `draft_unavailable` when the draft lane is down (send it without `draft` to render normally).

Default: false

H3 Max Multi Angle only (`video.hailuo_03_max_multi_angle`): a preset camera move around the `image_url` subject — `orbit` (one full 360° turn), `orbit_reverse`, `half_orbit`, `quarter_orbit`, `dolly_in`, `dolly_out`, `crane_up`, `low_angle`, `top_down`, `arc_push`, `spiral`, `hero_reveal`. Omit for the model default. Any other model returns 400 `unsupported_camera_trajectory`.

H3 Max Multi Angle only: explicit camera keyframes instead of `camera_path` — 2 to 12 objects `{ time, azimuth, elevation, distance }`. `time` runs 0 (first frame) to 1 (last); `azimuth` is degrees around the subject, signed and unbounded (360 = one full turn, up to 32 turns of total travel); `elevation` is -90 (below) to 90 (top-down); `distance` is in scene units, 1 = the source framing, smaller is closer. The first pose is held before its time and the last after it. Overrides `camera_path` when both are sent; a malformed list returns 400 `invalid_camera_trajectory`.

H3 Max Styles only (`video.hailuo_03_max_styles`, `capabilities.video_styles` at GET /v1/models) — and REQUIRED there (400 `video_style_required`): the baked-in look the prompt is rendered in. `vhs` (camcorder tape: scan lines, colour bleed, tracking wear), `retro_toon_70s` (1970s hand-painted cel animation), `low_poly` (faceted, flat-shaded retro 3D), `hand_drawn` (pencil-on-paper animation), `16bit_pixel` (16-bit console pixel art). Any other value is 400 `invalid_video_style`; sending it to any other model is 400 `unsupported_video_style`. The legal values are the model's `limits.video_styles`.

H3 Max Styles with `video_style: "vhs"` only: how worn the tape looks — `light`, `medium` or `heavy`. Omit for the model default (medium). Any other value is 400 `invalid_damage_level`; sending it with another style or another model is 400 `unsupported_damage_level`.

Default: medium

H3 Max Extend only (`video.hailuo_03_max_extend`): `extended` returns the source clip plus the new footage as one video, `continuation` returns only the new footage. Omit for the default (`extended`). Any other value is 400 `invalid_extend_output`; sending it to any other model is 400 `unsupported_extend_output`. Does not change the price.

Default: extended

H3 Max 3D to Video only (`video.hailuo_03_max_3d`): when you send NO `reference_image_urls`, the model generates up to this many appearance references itself (1-8, default 2) and each one is billed, so the cap is part of the quote. Ignored — and not billed — when reference images are sent. Outside 1-8 is 400 `invalid_max_generated_reference_images`; sending it to any other model is 400 `unsupported_max_generated_reference_images`.

Default: 2

H3 Max Insert only (`video.hailuo_03_max_insert`), and REQUIRED there with `insert_resume_time` (400 `insert_window_required`): the second of the source clip where the NEW scene begins — at least 1.625, at most 60. Seconds into `source_video_url` as supplied (the source is never trimmed first); decimals allowed. A non-number is 400 `invalid_insert_window`; sending it to any other model is 400 `unsupported_insert_window`.

H3 Max Insert only, REQUIRED there: the second of the source clip where the ORIGINAL footage picks up again after the new scene — later than `insert_start_time`, at most 60, and before the clip ends (leave some footage after it for the transition). The source is measured before the run exists, so a resume at or past its end is 400 `invalid_insert_window`, as is any window outside those bounds. The span it replaces does not set the new scene's length — `duration` does. Any other model: 400 `unsupported_insert_window`.

H3 Max Insert only: grade the new scene's colour to the source clip so the cut in and out is seamless. Send `false` only for a deliberate look change. Does not change the price. A non-boolean is 400 `invalid_color_match`; sending it to any other model is 400 `unsupported_color_match`.

Default: true

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

Optional id of one of your brands (`GET /v1/brands`). Grounds the clip server-side: its colors/style/voice lead the prompt, and its product images join `reference_image_urls` only where that cannot change the request's mode — when the clip already runs reference-to-video, or is text-only on a model with a reference endpoint (`capabilities.referenceImages`). With `image_url` (start frame — except on Kling O3 / Kling 4.0, whose reference endpoint keeps the frame), first/last frames or keyframes, or on a model without reference images, the brand grounds by text alone and the clip keeps its mode and inputs. With `source_video_url` the images ride along only where the clip's endpoint takes references (Kling O3 video-to-video reference, H3 Max 3D / Insert, Happy Horse edit) — never on `video.hailuo_03_max_recast`, whose references are the cast, so it grounds by text alone. Invalid or unowned id → 404 `invalid_brand_id`. POST /v1/models/estimate-cost with the same `brand_id` quotes exactly this.

Optional id of one of your moodboards (`GET /v1/moodboards`, or a board shared with you). Requires the `moodboards:read` scope in addition to `videos:write` (403 `insufficient_scope` otherwise). Styles the clip server-side: the board's composed style fragment follows any brand prefix at the head of the prompt, and its exemplar images join `reference_image_urls` only where that cannot change the request's mode: when the clip already runs reference-to-video (you, the brand or a template sent references), or is text-only on a model with a reference endpoint (`capabilities.referenceImages`) — filling only the reference slots the model has left. With `image_url` (start frame — except on Kling O3 / Kling 4.0, whose reference endpoint keeps the frame), first/last frames or keyframes, or on a model without reference images, the board styles by text alone and the clip keeps its mode and inputs. With `source_video_url` the exemplars ride along only where the clip's endpoint takes references (Kling O3 video-to-video reference, H3 Max 3D / Insert, Happy Horse edit) — never on `video.hailuo_03_max_recast` (its references are the cast; the board styles it by text). Unknown or inaccessible id → 404 `invalid_moodboard_id`. The run's `input` records `moodboard_id` and `moodboard_strength`. POST /v1/models/estimate-cost with the same `moodboard_id` quotes exactly this.

How hard the moodboard steers: `subtle` (prompt fragment only), `balanced` (fragment + up to 3 exemplars) or `strong` (fragment + as many exemplars as the model has reference slots for). Any other value → 400 `invalid_moodboard_strength`. Only read with `moodboard_id`.

Default: balanced

Your TRAINED MODELS to run this clip with — `[{ id, scale? }]`, up to 3 ids from `GET /v1/loras` (status `completed`), `scale` 0–4 (default 1). `video.hailuo_03` ONLY: every other model — including `video.hailuo_03_max` and `video.hailuo_03_max_turbo` — returns 400 `invalid_loras`. The model's kind picks the Hailuo 03 endpoint: a `style` or `keyframe` model runs image-to-video (prompt only, or prompt + `image_url`), a `subject` model runs reference-to-video (with or without `reference_image_urls` / video / audio), a `t2v` model runs text-to-video. Mixing kinds, or a start frame with a subject model, is a 400 `lora_mode_mismatch`; an id that is not yours is 404 `lora_not_found`; one still training is 409 `lora_not_ready`. The model's `trigger_phrase` is prepended to your prompt for you. Billed at the Hailuo 03 LoRA per-second rate (POST /v1/models/estimate-cost with `loras` quotes it).

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.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

The DRAFT: its run id (`run_…` from POST /videos/generations, or the `dash_video_…` id GET /runs lists for a draft made in the studio), or its `output.video_id`.

File this run's output into one of your PROJECTS (`GET /v1/projects`), exactly as if you had the project open in the studio. Edit access is checked before the run is created. Routes whose output is not an image, video or audio a project can hold return 400 `project_filing_unsupported`. The run echoes it back as `project_id`, and `GET /v1/runs?project_id=` lists everything made inside it.

The DRAFT: its run id (`run_…`, or a `dash_video_…` id) or its `output.video_id`.

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

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

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.

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

Absolute URL of the source video.

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

Default: video_upscale.topaz

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.

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

Absolute URL of the source image.

Either 2 or 4.

Default: 2

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

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?, text?, words? } — burn captions onto the finished cut. Preset ids come from `GET /v1/faceless-reels/caption-presets`. By default the words are transcribed from the cut's own audio; pass `text` (the authored transcript, ≤20000 chars — force-aligned against that audio so the words stay exactly as written) or `words` (`[{ text, start_sec, end_sec }]`, ≤5000 entries, ascending and non-overlapping — burned verbatim) to skip the guess. `text` and `words` are mutually exclusive. 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.

The edit, 1-1000 entries. Each: `id`, `type` ("video" | "image" | "audio" | "text"), `sourceId` (matches a `sources[].id`; omit for text), `startTime` + `duration` (seconds on the finished timeline), `sourceStartTime` (in-point within the source), `trackIndex` (Z-order, 0-64), `layout` ({ x, y: -100..100 percent offsets from centre, scale: 0.2-3, rotation: degrees }), `volume` (0-2), `muted`, and for text clips `textContent` + `textStyle` ({ fontSize, fontWeight, fontFamily, textColor, strokeColor, strokeWidth, backgroundOpacity, captionPresetId, captionWords, captionAnimation, blendMode, gradientColors, gradientDirection }), plus `speed` and `motion` — see below. RETIME: `speed` (video/audio, 0.25-4, default 1) is a playback rate. `duration` stays timeline seconds, so a 2s clip at `speed: 2` consumes 4s of source from `sourceStartTime`, and its audio is time-stretched to match. MOTION: `motion` ({ keyframes, motionBlur? }, video/image; ignored on text) animates the clip's framing on top of `layout` — a crash zoom is two keyframes. Each keyframe is { t, scale, x?, y?, ease? }: `t` is seconds from the CLIP's own start (clamped to its duration), `scale` MULTIPLIES `layout.scale` (0.2-4), `x`/`y` are frame percentages ADDED to `layout.x`/`layout.y`, and `ease` shapes the segment ARRIVING at that keyframe: linear, power1.in, power1.out, power1.inOut, power2.in, power2.out, power2.inOut, back.out, expo.out. At most 16 keyframes. `motionBlur` (0-1) smears the frame while it moves. Out-of-range values are clamped, not rejected. A punch-in needs no motion: split the clip and give the second half a larger `layout.scale`.

The media the clips point at, one entry per distinct source (max 300). Each: `id` (what `clips[].sourceId` matches) and `ref` — a run id (`run_…`), an upload `asset_url`, or an absolute https URL. Every ref is resolved and ffprobed before the timeline is stored, and the measurement comes back on the stored manifest as `sources[].measured`.

Frame width in pixels, 16-3840. The frame you authored against; a `final` render is exactly this size. Any aspect works: 1920×1080 (16:9), 1080×1920 (9:16), 1440×1080 (4:3), 1080×1080 (1:1).

Frame height in pixels, 16-3840.

Frames per second, 1-120.

Default: 30

Timeline length in seconds (max 7200). Defaults to the end of the last clip, and is raised to it if you send something shorter.

KEYFRAMED OVERLAY LAYERS (`version: 2`). `{ layers: [...], aboveCaptions?: boolean }`. Rendered by a headless browser into ONE transparent track and laid over the footage in a single pass, so it never touches your clips or your audio. Default paint order is footage < graphics < captions; `aboveCaptions: true` puts the graphics on top instead. EVERY LAYER carries `id` (unique, `[A-Za-z0-9][A-Za-z0-9_-]{0,63}`), `start`, `end`, `z` (paint order, ties break on id), `transform` ({ x, y: top-left in AUTHORING-FRAME pixels — the `width`/`height` you declared, not percentages; `width`, `height` optional; `scale`, `rotation` in degrees about the box centre, `opacity` 0-1 }), and optionally `transform3d` ({ rotateX, rotateY, perspective }) for a 2.5D tilt, `mask`, and `keyframes`. KIND is one of four. `text`: `text`, `font`, `size`, `weight` (100-900), `color`, `align` (left|center|right), `lineHeight`, `letterSpacing`, and an optional `entrance` ({ kind: fade-up|pop|typewriter|slide|blur-in, unit: word|char|line, stagger, duration }) that splits the copy and staggers it in. `image`: `src` (an https URL or `source:<id>` naming one of your `sources[]`), `fit` (cover|contain|fill), `radius`. `shape`: `shape` (rect|ellipse|line), `fill`, `stroke`, `strokeWidth`, `radius`. `counter`: `from`, `to`, `ease`, the same type fields as `text`, and `format` ({ style: integer|decimal1|percent, prefix, suffix, group }) — the number is written out on every frame, so scrubbing backwards shows the same digits as scrubbing forwards. KEYFRAMES are `{ property, t, value, ease }[]`. `property` is one of `x`, `y`, `scale`, `rotation`, `opacity`, `rotateX`, `rotateY`. `t` is ABSOLUTE composition time (not an offset from the layer's `start`) and must be strictly increasing within a property and inside `[start, end]`. `ease` describes the segment ARRIVING at that keyframe and is ignored on the first one. A property with no keyframes holds its `transform` value; a property with keyframes starts at its first one. EASES, exactly nine: `linear`, `power1.in`, `power1.out`, `power1.inOut` (quad), `power2.in`, `power2.out`, `power2.inOut` (cubic), `back.out`, `expo.out`. FONTS, exactly two, both vendored into the renderer: `Inter` and `Outfit`, any weight 100-900. Nothing is fetched at render time and there is no fallback family, so the type you ask for is the type you get. MASK is `{ kind: rect|ellipse|image, x, y, width, height, radius, src }`. The box is FRACTIONS of the layer box (0-1, default the whole box) so a mask lands identically at preview and final scale; `rect` takes `radius` as a fraction too, and `image` takes a `src` whose alpha is the matte. COLOURS are hex (`#rgb`, `#rrggbb`, `#rrggbbaa`) or `rgb()`/`rgba()`. Named colours and `var()` are rejected. LIMITS: 50 layers, 200 keyframes per layer, 2000 characters of text per layer.

A LOOK graded over the whole film's footage (video and image clips); text, captions and graphics layers sit on top of it ungraded: { preset, intensity?, grain? }. `preset` is one of `none`, `dvd_35mm`, `camcorder`, `flash_editorial`. `dvd_35mm` is the house look — standard-definition softness, a little compression smear, warm-neutral curves with lifted blacks and rolled highlights, highlight bloom, a soft vignette and moving film grain. `camcorder` is a consumer-video look and `flash_editorial` an on-camera-flash look; `none` is no grade. `intensity` (0-1, default 1) blends the grade; `grain` (0-1, default 0.5) sets the grain alone. An unknown preset is a 400. Omit it and the manifest hashes exactly as before.

A name for the timeline.

Tag this timeline and every render of it with one of your PROJECTS (`GET /v1/projects`), so `GET /v1/runs?project_id=` finds them. The rendered file is NOT filed as a project item — a render produces run output, not a `videos` document a project can hold.

Team (workspace) this timeline belongs to. Requires the `teams:read` scope.

The timeline id returned by `POST /v1/videos/timelines`.

The timeline to replace.

The revision you read. Sent here or as an `If-Match` header (the header wins). A mismatch is 409 `timeline_rev_conflict`; neither is 428.

TARGETED EDITS instead of a replacement manifest (send one or the other, never both). 1-100 of: `{ op: add|update|remove, target: clip|source|layer, id, value? }` — `update` merges `value` into that entity recursively (arrays replace), so `{ op: "update", target: "clip", id: "c1", value: { speed: 2 } }` retimes one clip and leaves the rest alone; `{ op: "frame", value: { width?, height?, fps?, duration? } }` — e.g. `{ width: 1440, height: 1080 }` for 4:3; `{ op: "finish", value: { preset?, intensity?, grain? } | null }` — merged onto the current finish (a preset is required if there is none yet), `null` removes it. The whole result is validated exactly like a replace before it is saved.

The complete new clip list — same shape as on create. Required on a replace.

The complete new source table — same shape as on create. Re-resolved and re-probed on every PATCH. Required on a replace.

Frame width in pixels, 16-3840. Required on a replace.

Frame height in pixels, 16-3840. Required on a replace.

Frames per second, 1-120.

Default: 30

Timeline length in seconds.

The complete new graphics block — same shape as on create. Omitting it REMOVES the layers and drops the manifest back to `version: 1`, like every other field on a replace.

The whole-film look — same shape as on create. Omitting it on a replace REMOVES the look.

Rename the timeline. Omit to leave the title alone.

The timeline to render.

"preview" (480p on the short edge, cached) or "final" (the manifest's full frame).

Default: preview

Render only if the timeline is still at this revision. A guard, not a selector — there is no way to render a superseded revision, so a stale `rev` is 409 rather than a render of something you did not ask for.

The timeline whose renders to list.

How many runs to return, 1-100.

Default: 25

Absolute URL to the source video. Required for every model except the photo-input `lipsync.h3_max_lipsync`.

Absolute URL to the photo to animate. Required for (and only accepted by) `lipsync.h3_max_lipsync`. Aspect ratio must be between 0.4 and 2.5.

`lipsync.h3_max_lipsync` only: `480P`, `768P`, `1080P` (2x) or `2K` (4x).

Default: 768P

`lipsync.h3_max_lipsync` only: transcribe the audio to guide the mouth shapes.

Default: false

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.

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

The text to speak. Required unless `dialogue` is sent. 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 (`clone_<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`. The default, `speech.elevenlabs_v4_turbo`, is Eleven v4 expressiveness (audio tags) at ~100 ms latency and half v4's cost; `speech.elevenlabs_v4` is the most expressive. Both cap a request at 10,000 characters and take only `stability` + `similarity_boost` voice settings (`speed`, `style` and `use_speaker_boost` are ignored). With `model` omitted, the request runs on `speech.elevenlabs_flash_v2_5` (40,000 characters, same price) instead when the text is longer than 10,000 characters, when it sets a `speed` other than 1, or when `voice_id` is one of your account's cloned ElevenLabs voices (ElevenLabs asks for those to be retrained for v4). `speech.elevenlabs_turbo_v2_5` still works but is deprecated upstream.

Default: speech.elevenlabs_v4_turbo

Text to Dialogue (`speech.elevenlabs_dialogue_v4` or `speech.elevenlabs_dialogue_v3`, implied when present): an ORDERED array of `{ text, voice_id }` lines rendered as one audio file with matched prosody. Runs on Eleven v3 when `model` is `speech.elevenlabs_dialogue_v3` or `speech.elevenlabs_v3`, otherwise on Eleven v4 (the default dialogue model); the run records and bills that dialogue model. Up to 10 distinct ElevenLabs voices and 2000 characters in total; lines accept audio tags like `[whispers]` or `[laughs]`. Replaces `text` + `voice_id`. Cloned `clone_*` voices are not supported here.

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

ElevenLabs only — ISO 639-1 code (e.g. `es`, `pt`) that enforces the spoken language on Flash/Turbo/v3/v4. Ignored by Multilingual v2 (it auto-detects), by cloned voices, and by any model that does not support the given language.

Speaking rate. ElevenLabs: 0.7–1.2 (1 = natural, clamped). Sending `speed` without a model uses `speech.elevenlabs_flash_v2_5` automatically; an explicit v4 model (`speech.elevenlabs_v4`, `speech.elevenlabs_v4_turbo`) ignores it. Seed Audio 1.0: 0.5–2.

ElevenLabs only — 0..4294967295 for best-effort reproducibility (also applies to `dialogue`).

ElevenLabs only — the text spoken immediately BEFORE this request (request stitching). Keeps prosody continuous when a long script is generated in chunks.

ElevenLabs only — the text spoken immediately AFTER this request (request stitching).

ElevenLabs only — `auto` (default), `on` (always expand numbers/abbreviations; adds latency) or `off` (read exactly as written).

Default: auto

ElevenLabs only — `{ stability, similarity_boost, style, use_speaker_boost, speed }` overrides; the v4 models use only `stability` + `similarity_boost`. For `dialogue`, `stability` is a top-level field: snapped to 0 | 0.5 | 1 on v3, any value 0–1 on v4.

ElevenLabs only — return per-word `words: [{ word, start, end }]` in the run output (and `voice_segments` for `dialogue`). Derived from the exact input text, so nothing is misheard.

Default: false

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

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

File this run's output into one of your PROJECTS (`GET /v1/projects`), exactly as if you had the project open in the studio. Edit access is checked before the run is created. Routes whose output is not an image, video or audio a project can hold return 400 `project_filing_unsupported`. The run echoes it back as `project_id`, and `GET /v1/runs?project_id=` lists everything made inside it.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

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 / music_v2_5 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`. Omitted, it is `music.elevenlabs_music_v2_5` — the newest ElevenLabs model — and a chunks-shaped `composition_plan` also runs on it. `music.elevenlabs_music_v1` is deprecated upstream; a sections-shaped `composition_plan` still selects it. `music.elevenlabs_music_v2` stays available when named and takes the same prompt, chunks plan, timestamps and inpainting fields as v2.5.

Default: music.elevenlabs_music_v2_5

Video-to-music (ElevenLabs only): score this footage instead of composing from a prompt. The track's length equals the video's (≤600s, ≤200MB); `prompt` becomes an optional description (≤1000 chars) and `tags` steer the style. Cannot be combined with `composition_plan`; billed per second of video.

Video-to-music only — up to 10 style tags (e.g. `cinematic`, `upbeat`).

ElevenLabs only — keep the song server-side so it can be inpainted. With `include_details: true` the run output carries `song_id`; reference it in a later chunks-shaped (music_v2 / music_v2_5) `composition_plan` as `{ song_id, range: { start_ms, end_ms } }` chunks to keep those bars verbatim and regenerate only the other chunks.

Default: false

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. Both Lyria models ignore it — `music.lyria3_pro` produces a ~3 min song, `music.lyria_3_5` a full-length one whose length you steer in the prompt (timestamps or a duration hint).

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 and music_v2_5 always enforce 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. `music.lyria_3_5` and `music.lyria3_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).

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

File this run's output into one of your PROJECTS (`GET /v1/projects`), exactly as if you had the project open in the studio. Edit access is checked before the run is created. Routes whose output is not an image, video or audio a project can hold return 400 `project_filing_unsupported`. The run echoes it back as `project_id`, and `GET /v1/runs?project_id=` lists everything made inside it.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

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.

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

File this run's output into one of your PROJECTS (`GET /v1/projects`), exactly as if you had the project open in the studio. Edit access is checked before the run is created. Routes whose output is not an image, video or audio a project can hold return 400 `project_filing_unsupported`. The run echoes it back as `project_id`, and `GET /v1/runs?project_id=` lists everything made inside it.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

Absolute URL of the source recording (audio or video, up to 5 minutes). Your own `POST /v1/uploads` asset URLs work as-is.

The ElevenLabs voice to convert INTO. List options via `/audio/voices?include=stock`.

Speech-to-speech model id.

Default: eleven_multilingual_sts_v2

Strip background noise from the source before converting.

Default: false

File the converted audio into one of your PROJECTS (`GET /v1/projects`) when the run completes.

Title for the converted audio in your library.

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

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`: `transcription.whisper_v1` or `transcription.elevenlabs_scribe_v2`.

Default: transcription.whisper_v1

Scribe only — ISO 639-1/639-3 code of the spoken language. Omit to auto-detect.

Scribe only — label speakers; every word carries `speaker_id` and segments break on speaker change.

Default: true

Scribe only — expected speaker count, 1–32. Omit for automatic.

Scribe only — domain vocabulary (names, products, jargon) to bias recognition towards. Up to 1000 terms, <50 chars each. Adds a 30% premium upstream.

Scribe only — emit `[laughter]`, `[applause]` etc. as `type: "audio_event"` words.

Default: true

Scribe only — drop fillers and disfluencies ("um", repeated words) for a clean read.

Scribe only — detect entities: `all`, `pii`, `phi`, `pci`, `other`, `offensive_language`. Results land in `output.entities`.

Scribe only — redact the listed entity classes (subset of `entity_detection`) in the transcript text.

Scribe only — label speaker roles (e.g. agent / customer) where detectable.

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

File this run's output into one of your PROJECTS (`GET /v1/projects`), exactly as if you had the project open in the studio. Edit access is checked before the run is created. Routes whose output is not an image, video or audio a project can hold return 400 `project_filing_unsupported`. The run echoes it back as `project_id`, and `GET /v1/runs?project_id=` lists everything made inside it.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

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

Single source image (absolute https URL or an upload `asset_url`). Provide this OR `image_urls`.

1-4 images of the SAME object from different angles. More than one routes to the multi-image endpoint. More than four is 400 `too_many_images`.

A `model_3d_generation` alias from `GET /v1/models` — `3d.meshy_v7` (default) or `3d.meshy_v6`.

Generate surface textures.

Default: true

Also produce physically-based rendering maps (metallic / roughness / normal).

Default: false

Produce a rigged skeleton. Highest-priced variant, and it takes precedence over the PBR and texture keys.

Default: false

Animate the rigged mesh. Requires `enable_rigging`.

Default: false

Which library action to animate, 0-696. Requires `enable_animation`; out of range is 400 `invalid_animation_action_id`.

Real-world height in metres, used to scale the rig.

"quad" or "triangle".

Target polygon count, 100-300000. Out of range is 400 `invalid_target_polycount`.

"standard" or "lowpoly".

Higher-fidelity geometry. Meshy v7 with a SINGLE image only; silently dropped for v6 and for multi-image requests.

Remesh the generated geometry.

"a-pose", "t-pose", or "" to leave the pose alone.

"off", "auto" or "on".

Steer the texturing pass (with `should_texture`).

Bill a workspace (team) credit pool instead of the personal balance. Requires the `teams:read` scope and a spending role; an insufficient pool is 402 `team_pool_insufficient`.

A `quote_token` from `POST /v1/models/estimate-cost`, to be charged the price you were quoted. May also be sent as the `X-Genfire-Quote` header.

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-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5`, `gpt-6-sol`). Defaults to `claude-fable-5-1`.

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

The complete single-file game. Must start with `<!DOCTYPE html>` or `<html>` and end with `</html>`; 200 bytes to 1,500,000 bytes.

Name in the gallery and the library, trimmed to 80 chars.

Default: the document's own <title>, else the first 60 chars of `brief`, else "Deployed game"

What the game is, max 2000 chars. Stored as the prompt and used for the thumbnail.

Redeploy a game you already own, in place at the same `play_url`. A game you do not own is 404 `game_not_found`.

Inject the Genfire multiplayer relay client before hosting. Players co-play by opening the play link with the same `?room=` value.

Default: false

Bill a workspace (team) credit pool instead of the personal balance. Requires the `teams:read` scope and a spending role.

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

Only runs billed to this WORKSPACE pool (`GET /v1/teams`). Narrows the listing to runs made through this API — a dashboard generation has no notion of which workspace paid for it.

Only runs made inside this PROJECT (`GET /v1/projects`) — everything an agent produced while working in it, whatever the capability. Same narrowing as `team_id`.

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.

Filter the edit list to one family: `relight`, `swap`, `reframe`, `cleanup`, `restyle` or `draw`. Anything else is a 400 `invalid_group`. The motion list is returned whole either way.

Maximum entries to return (1-100).

Default: 60

Runs to return, 1-48 (larger values are clamped to 48).

Default: 12

`next_cursor` from the previous page. Anything else is a 400 `invalid_cursor`.

Display name (≤120 chars).

`style`, `subject`, `keyframe` or `t2v`. Fixes the trainer and the Hailuo 03 endpoint the model runs on.

Training clips as objects: `{ url, caption?, reference_urls? }`. Up to 40. `reference_urls` (≤4 per clip) are subject-model sidecars.

Shorthand for `clips` when you have no captions: an array of video URLs. Send one of `clips` / `clip_urls`, not both.

A pre-built .zip of training videos (with optional same-name .txt captions and, for subject models, `<clip>.ref_1..ref_4.<ext>` sidecars). Skips archive assembly. Cannot be combined with `clips` / `clip_urls`.

A short unique token (≤80 chars, e.g. `WARMFILM style`) that activates the model. Prepended to captions during training and to your prompt at inference.

Training steps, 100–6000 (billed per 100). More steps = stronger fit and higher cost.

Default: 2000

LoRA rank: 8, 16, 32, 64 or 128. Higher ranks capture more detail and cost nothing extra, but overfit small datasets.

Default: 32

0.000001–1.

Default: 0.0002

`low`, `medium` or `high` — the resolution clips are trained at.

Default: medium

Training aspect: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16.

Default: 16:9

Frames per training sample: 22, 39, 56, 73, 90, 107 or 124.

Default: 73

8–60.

Default: 24

Cut clips at scene changes before training. Defaults to true, except for subject models (false — splitting drops the reference sidecars).

Fail the run on any unreadable clip instead of skipping it.

Default: false

Subject models only: warm-start from one of your completed subject models (same as POST /loras/{loraId}/continue).

Tag a subject model as belonging to one of your influencers.

Must be `true`: you confirm you hold the rights to every clip in the training set.

Bill a WORKSPACE credit pool instead of your balance (`GET /v1/teams`). Requires `teams:read`.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

`style`, `subject`, `keyframe` or `t2v`.

100–6000.

Default: 2000

`pending`, `training`, `completed` or `failed`.

1–50 (default 50).

Trained model id.

The completed subject model to continue from.

Additional training steps, 100–6000.

Default: 2000

Name for the new model. Defaults to `<original name> (continued)`.

New training clips (`{ url, caption?, reference_urls? }`). Omit to reuse the original dataset archive.

Shorthand for `clips` (URLs only).

Required when sending new clips.

Bill a workspace pool. Requires `teams:read`.

Trained model id.

Filter to one state: `queued`, `training`, `completed` or `failed`. Anything else is 400 `invalid_status`.

Max styles to return, 1-50.

Default: 50

A style skill id from `GET /v1/style-skills`. A skill that is not a style skill is 404 `skill_not_found`.

Training steps, 100-4000. Billed per 100-step unit, rounded up. Out of range is 400 `invalid_steps`.

Default: 1000

Bill a workspace (team) credit pool instead of the personal balance. Requires the `teams:read` scope and a spending role.

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.

Bill this run 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. A route that cannot bill a pool yet returns 400 `team_billing_unsupported` rather than quietly charging you. The run echoes it back as `team_id`.

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 signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

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

Which page to price. Defaults to the first page.

Node ids to price — their upstream dependencies are included automatically. Defaults to the same selection a run would use.

Per-run parameter overrides shaped as `{ nodeId: { paramKey: value } }`. Priced exactly as the run would apply them — cost-relevant params (durations, resolutions, models) change the quote.

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

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

A preset id from `GET /presets`.

A preset id from `GET /presets`.

The same `inputs` object you intend to run with, keyed by an input `name` from `GET /presets/{presetId}`. It is part of what the quote is bound to, so price-changing inputs must be present here.

Validated exactly as on the run, so a workspace the run would reject cannot be quoted against.

Validated exactly as on the run.

A preset id from `GET /presets`.

Input values keyed by an input `name` from `GET /presets/{presetId}` (`"<node_id>.<param>"`). A bare `"<param>"` is accepted when exactly one node exposes it. Values must be primitives. Unknown or ambiguous keys are rejected rather than ignored.

Bill this run to a team pool instead of your own balance. You must be a billable member of the team.

File the run's image and video outputs into this studio project.

Required once for a paid preset: confirms the one-time unlock charge of `price_credits`. Later runs of the same preset do not need it.

A signed price quote from the matching estimate endpoint, binding this submit to the price you were shown. May also be sent as the `X-Genfire-Quote` header. The token carries the quoted inputs, so it is only spendable on the request it was issued for: 409 `quote_expired` past its 10-minute life, 409 `quote_mismatch` when the inputs or the price no longer match, 401 `quote_invalid` when the signature does not verify. Every 409 carries a FRESH quote in the problem body so you can resubmit in one step.

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

Optional item status filter: `queued`, `processing`, `completed`, or `failed`. `?status=failed` is the list you feed to the retry endpoint.

The batch id returned by `POST /batches`.

The batch item id (`batch_item_...`).

The batch id returned by `POST /batches`.

The batch item id (`batch_item_...`). Must be in status `failed`.

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

Bill the whole batch to a team (workspace) pool instead of your own balance. Requires the `teams:read` scope and a billable role on that team.

Array of batch items. Each item must have an `input` object, and may carry an optional `custom_id`.

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.