video_generate
Generate shot videos and start video timeline exports, with discoverable model constraints, reference roles, prompt/default resolution, and asset handoff metadata.
When to use
Use for video generation or timeline export workflows.
Call `generate_video` with `phase=readiness` before a custom start payload when the caller needs supported models, roles, duration options, aspect ratios, resolutions, audio support, default settings, or credit estimates.
Use `generate_video` start with `payload.shot_card_id` to generate one shot; BeatBandit automatically derives the prompt, defaults, selected shot image, recurring references, and supported same-shot audio unless the caller provides explicit overrides.
`payload.autofill_from_shot=true` is accepted as an explicit signal for that same shot-derived path, but it is not required when `payload.shot_card_id` is present and prompt, references, or defaults are omitted.
Omit `payload.model_path` when the caller wants BeatBandit to use the caller's saved default video model for this workflow.
Use `payload.references[]` for explicit references. Supported reference sources are `shot_asset_id`, `shot_element_asset_id`, `video_asset_id`, `media_asset_id`, and one-off `external_url`; supported roles depend on the selected model.
Omit `payload.duration_seconds` when the caller wants BeatBandit to use the shot card duration when present, then the selected model default.
Use `payload.no_background_music=true` when the model may generate audio but the clip should avoid score, soundtrack, or background music.
When not to use
Do not use for still-image generation.
Do not pass raw provider-specific params; BeatBandit exposes validated top-level controls such as `duration_seconds`, `aspect_ratio`, `resolution`, `audio_enabled`, `seed`, and `references`.
Examples
“Generate a video from the selected shots.”
“Start one shot video from `shot_card_id` only, reusing the same prompt/reference/duration defaults the website would derive.”
“Check readiness, then start a Seedance reference-to-video shot using a storyboard image, recurring element references, `duration_seconds=15`, `aspect_ratio=16:9`, and `no_background_music=true`.”
“Generate a one-off test video with `references[].external_url` when the user provides a temporary HTTPS reference image.”
Anti-examples
- Create music for this scene.
- Generate an individual storyboard panel; use `image_generate(workflow=generate_shot)` instead.
Workflows
Switch behavior by setting the workflow input field.
generate_video
timeline_export_start
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"type": "string",
"enum": [
"generate_video",
"timeline_export_start"
]
},
"phase": {
"type": "string"
},
"project_id": {
"type": "integer"
},
"job_id": {
"type": "string",
"minLength": 1
},
"payload": {
"type": "object",
"properties": {
"shot_card_id": {
"type": "integer"
},
"prompt": {
"type": "string",
"minLength": 1
},
"model_path": {
"type": "string",
"minLength": 1
},
"autofill_from_shot": {
"type": "boolean",
"description": "Optional explicit request to derive prompt, references, and defaults from shot_card_id. Shot-scoped starts do this automatically when prompt, references, or defaults are omitted."
},
"input_mode": {
"type": "string",
"enum": [
"text_to_video",
"image_to_video",
"text_and_image"
],
"description": "Video input mode. Use readiness to discover what the selected model supports."
},
"duration_seconds": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Requested video duration in seconds. Must fit the selected model's allowed durations."
},
"aspect_ratio": {
"type": "string",
"description": "Requested output aspect ratio, such as 16:9, 9:16, 1:1, or auto when supported by the model."
},
"resolution": {
"type": "string",
"description": "Requested output resolution, such as 480p, 720p, or 1080p when supported by the model."
},
"audio_enabled": {
"type": "boolean",
"description": "Whether to ask the provider for generated video audio when the selected model supports audio."
},
"no_background_music": {
"type": "boolean",
"description": "When true, BeatBandit adds explicit prompt direction to avoid score, soundtrack, and background music while still allowing diegetic scene sound."
},
"seed": {
"type": "integer",
"description": "Optional generation seed when supported by the selected provider model."
},
"references": {
"type": "array",
"description": "Reference inputs for the video model. Use readiness.model_summary to choose valid roles and limits.",
"maxItems": 20,
"items": {
"type": "object",
"required": [
"input_role"
],
"properties": {
"input_role": {
"type": "string",
"enum": [
"start_frame",
"end_frame",
"reference_image",
"reference_video",
"reference_audio"
],
"description": "Model-facing role for this reference."
},
"source_kind": {
"type": "string",
"enum": [
"image",
"video",
"audio"
],
"description": "Reference media kind. If omitted by the backend API, it is inferred from input_role/source."
},
"shot_asset_id": {
"type": "integer",
"description": "Existing BeatBandit shot image asset id."
},
"shot_element_asset_id": {
"type": "integer",
"description": "Existing BeatBandit recurring element image asset id."
},
"video_asset_id": {
"type": "integer",
"description": "Existing BeatBandit video asset id for reference-video models."
},
"media_asset_id": {
"type": "integer",
"description": "Existing BeatBandit audio media asset id for reference-audio models."
},
"additional_shot_element_asset_ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Additional image references for the same recurring element, supported only for reference_image shot-element inputs."
},
"external_url": {
"type": "string",
"format": "uri",
"description": "HTTPS image, video, or audio URL to pass as a one-off external reference. Prefer BeatBandit asset ids when the reference should be reusable."
}
},
"oneOf": [
{
"required": [
"shot_asset_id"
]
},
{
"required": [
"shot_element_asset_id"
]
},
{
"required": [
"video_asset_id"
]
},
{
"required": [
"media_asset_id"
]
},
{
"required": [
"external_url"
]
}
],
"additionalProperties": false
}
},
"select_as_primary": {
"type": "boolean",
"description": "Whether the finalized video should become the selected video take for the shot."
},
"add_to_timeline": {
"type": "boolean",
"description": "Whether to insert the finalized video asset onto the relevant video timeline."
},
"scope_type": {
"type": "string",
"minLength": 1
},
"scope_code": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": true
}
},
"allOf": [
{
"if": {
"properties": {
"workflow": {
"const": "generate_video"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start",
"finalize",
"cancel",
"rescue"
]
}
},
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"required": [
"shot_card_id"
],
"properties": {
"shot_card_id": {
"type": "integer"
},
"prompt": {
"type": "string",
"minLength": 1
},
"model_path": {
"type": "string",
"minLength": 1
},
"autofill_from_shot": {
"type": "boolean",
"description": "Optional explicit request to derive prompt, references, and defaults from shot_card_id. Shot-scoped starts do this automatically when prompt, references, or defaults are omitted."
},
"input_mode": {
"type": "string",
"enum": [
"text_to_video",
"image_to_video",
"text_and_image"
]
},
"duration_seconds": {
"type": "number",
"exclusiveMinimum": 0
},
"aspect_ratio": {
"type": "string"
},
"resolution": {
"type": "string"
},
"audio_enabled": {
"type": "boolean"
},
"no_background_music": {
"type": "boolean"
},
"seed": {
"type": "integer"
},
"references": {
"type": "array",
"maxItems": 20,
"items": {
"type": "object",
"required": [
"input_role"
],
"properties": {
"input_role": {
"type": "string",
"enum": [
"start_frame",
"end_frame",
"reference_image",
"reference_video",
"reference_audio"
]
},
"source_kind": {
"type": "string",
"enum": [
"image",
"video",
"audio"
]
},
"shot_asset_id": {
"type": "integer"
},
"shot_element_asset_id": {
"type": "integer"
},
"video_asset_id": {
"type": "integer"
},
"media_asset_id": {
"type": "integer"
},
"additional_shot_element_asset_ids": {
"type": "array",
"items": {
"type": "integer"
}
},
"external_url": {
"type": "string",
"format": "uri"
}
},
"oneOf": [
{
"required": [
"shot_asset_id"
]
},
{
"required": [
"shot_element_asset_id"
]
},
{
"required": [
"video_asset_id"
]
},
{
"required": [
"media_asset_id"
]
},
{
"required": [
"external_url"
]
}
],
"additionalProperties": false
}
},
"select_as_primary": {
"type": "boolean"
},
"add_to_timeline": {
"type": "boolean"
}
}
}
}
}
},
{
"if": {
"properties": {
"phase": {
"enum": [
"finalize",
"cancel",
"rescue"
]
}
}
},
"then": {
"required": [
"job_id"
]
}
}
]
}
},
{
"if": {
"properties": {
"workflow": {
"const": "timeline_export_start"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"start",
"status",
"cancel"
]
}
},
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"required": [
"scope_type",
"scope_code"
],
"properties": {
"scope_type": {
"type": "string",
"minLength": 1
},
"scope_code": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
{
"if": {
"properties": {
"phase": {
"enum": [
"status",
"cancel"
]
}
}
},
"then": {
"required": [
"job_id"
]
}
}
]
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"resource_updated_at": {
"type": "string",
"format": "date-time",
"description": "Generic updated_at value for read/propose outputs that need a round-trippable optimistic-concurrency timestamp."
},
"credits_charged": {
"type": "integer",
"minimum": 0,
"description": "Credits charged for this capability call when credit_metered=true."
},
"credits_skipped_reason": {
"type": "string",
"description": "Present instead of credits_charged when the capability intentionally skipped billing (e.g. cache hit, no-op, failed_before_llm)."
},
"pipeline_state": {
"$ref": "./_common/pipeline_state.schema.json"
},
"next_actions": {
"type": "array",
"items": {
"$ref": "./_common/next_action.schema.json"
}
}
},
"additionalProperties": true
}