asset_upload
Upload a local, public-URL, or base64 image/audio into BeatBandit as a shot image, recurring shot-element reference, scene moodboard asset, project visual-style reference, or reusable voice reference.
When to use
Use when you already have a generated PNG/JPEG/WebP on disk and need it stored in BB for reuse in prompts, moodboards, shot references, or later video/image generation.
Use when you already have a WAV/MP3/PCM/Ogg voice sample that should become a reusable `reference_audio` media asset.
Use `file_path` only when the BeatBandit MCP runtime can read the same local filesystem path. If the file is visible to your shell/Codex workspace but not to MCP, read it locally and send `content_base64` with `source_filename` and `mime_type`.
Use `source_url` for Scenario/CDN-hosted images or audio when the remote BeatBandit MCP server cannot read local `file_path` values.
Use `target_type=shot_asset` with `shot_card_id` to attach an existing storyboard, first-frame, or last-frame image to one shot.
Use `target_type=shot_element_asset` with `element_id` to attach a reference image to an existing recurring character, environment, object, style, or other element.
Use `target_type=scene_moodboard_asset` with `parent_scene_code` to attach a scene-level moodboard reference board.
Use `target_type=project_visual_style_asset` to attach a master style reference image to the project default visual style, or pass `project_visual_style_id` for a specific project visual style.
Use `target_type=reference_audio_asset` with a short clean voice sample before `voice_profile(operation=add_reference)`.
When not to use
Do not use to create the recurring element itself; use `shot_mutate(entity_type=element, operation=upsert_element)` first if the element does not exist.
Do not use to generate a new image from a prompt; use `image_generate`.
Do not use to generate scene audio; use `media_generate(workflow=scene_audio)`.
Do not use to inspect the uploaded asset after creation; use `asset_display`.
Examples
“Upload a locally rendered storyboard frame to shot card 123 as `shot_asset_type=storyboard`.”
“Upload a Codex-local image by base64-encoding the file bytes and passing `content_base64`, `source_filename`, and `mime_type` when MCP cannot read the caller's path.”
“Upload `mira-origin-05-rural-north-american-outsider.png` as Mira's active recurring character reference.”
“Upload `mira-voice-clean.mp3` as `target_type=reference_audio_asset`, then attach it to Mira's voice profile.”
“Upload `clean-moodboard-02-extra-clean-surfaces.png` as a selected scene moodboard asset.”
“Upload `master-style-frame.png` as the project default visual-style reference so later moodboards, recurring images, and shot images inherit that look.”
“Upload a local generated prop reference image to an existing recurring object element.”
Anti-examples
- Create the missing Mira recurring element from scratch; use `shot_mutate`.
- Generate a clean-surface moodboard from the shot list; use `image_generate(workflow=generate_scene_moodboard)`.
- List all uploaded moodboards; use `project_assets_query(asset_kind=scene_moodboard)`.
- Add the uploaded voice sample to a profile; use `voice_profile(operation=add_reference)`.
Backend capabilities
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"project_id",
"target_type"
],
"properties": {
"project_id": {
"type": "integer"
},
"target_type": {
"type": "string",
"enum": [
"shot_asset",
"shot_element_asset",
"scene_moodboard_asset",
"project_visual_style_asset",
"reference_audio_asset"
]
},
"file_path": {
"type": "string",
"description": "Local file path read by the BeatBandit MCP runtime process, not necessarily by the caller's shell/Codex workspace. Use only when the runtime shares that filesystem; otherwise send content_base64 with source_filename/mime_type or provide source_url."
},
"source_url": {
"type": "string",
"description": "Public http(s) image or audio URL fetched by the BeatBandit MCP runtime/backend. Use this for Scenario/CDN-hosted assets when the MCP server cannot read local paths."
},
"content_base64": {
"type": "string",
"description": "Base64-encoded image or audio bytes. Use this when the file is local to the caller but the BeatBandit MCP runtime cannot read the caller's file_path."
},
"source_filename": {
"type": "string"
},
"mime_type": {
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"if_match_updated_at": {
"type": "string"
},
"element_id": {
"type": "integer"
},
"project_visual_style_id": {
"type": "integer",
"description": "For project_visual_style_asset uploads. Omit to attach to the current project default visual style."
},
"asset_type": {
"type": "string",
"description": "For shot_element_asset uploads only.",
"enum": [
"reference",
"thumbnail"
],
"default": "reference"
},
"shot_card_id": {
"type": "integer",
"description": "Required for shot_asset uploads."
},
"shot_asset_type": {
"type": "string",
"description": "For shot_asset uploads only.",
"enum": [
"storyboard",
"first_frame",
"last_frame"
],
"default": "storyboard"
},
"variant_label": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"is_additional_reference": {
"type": "boolean"
},
"is_selected": {
"type": "boolean",
"description": "For shot_asset uploads, select this asset for the shot and export by default."
},
"composition_mode": {
"type": "string",
"description": "Optional shot_asset display/generation metadata. Defaults to mcp_upload."
},
"aspect_ratio": {
"type": "string",
"description": "Optional shot_asset display/generation metadata. Defaults to 16:9."
},
"parent_scene_code": {
"type": "string",
"description": "Scene/scope code for scene moodboard uploads. Defaults to full-project moodboard scope."
},
"prompt": {
"type": "object",
"additionalProperties": true
},
"title": {
"type": "string",
"description": "For reference_audio_asset uploads."
},
"duration_seconds": {
"type": "number",
"minimum": 0,
"maximum": 30,
"description": "Known duration for reference_audio_asset uploads. Reference voice samples should stay within the selected model limit."
}
},
"oneOf": [
{
"required": [
"file_path"
],
"not": {
"anyOf": [
{
"required": [
"content_base64"
]
},
{
"required": [
"source_url"
]
}
]
}
},
{
"required": [
"content_base64"
],
"not": {
"anyOf": [
{
"required": [
"file_path"
]
},
{
"required": [
"source_url"
]
}
]
}
},
{
"required": [
"source_url"
],
"not": {
"anyOf": [
{
"required": [
"file_path"
]
},
{
"required": [
"content_base64"
]
}
]
}
}
],
"allOf": [
{
"if": {
"properties": {
"target_type": {
"const": "shot_asset"
}
}
},
"then": {
"required": [
"shot_card_id"
]
}
},
{
"if": {
"properties": {
"target_type": {
"const": "shot_element_asset"
}
}
},
"then": {
"required": [
"element_id"
]
}
},
{
"if": {
"properties": {
"target_type": {
"const": "scene_moodboard_asset"
}
}
},
"then": {
"not": {
"required": [
"element_id"
]
}
}
},
{
"if": {
"properties": {
"target_type": {
"enum": [
"project_visual_style_asset",
"reference_audio_asset"
]
}
}
},
"then": {
"not": {
"required": [
"element_id"
]
}
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"operation",
"target_type",
"source_type",
"asset_id",
"asset"
],
"properties": {
"operation": {
"type": "string",
"const": "upload"
},
"target_type": {
"type": "string",
"enum": [
"shot_asset",
"shot_element_asset",
"scene_moodboard_asset",
"project_visual_style_asset"
]
},
"source_type": {
"type": "string",
"enum": [
"shot_asset",
"shot_element_asset",
"scene_moodboard_asset",
"project_visual_style_asset"
]
},
"asset_id": {
"type": "integer"
},
"asset": {
"type": "object"
},
"asset_updated_at": {
"type": "string"
},
"project_visual_style_id": {
"type": "integer"
},
"style": {
"type": "object"
},
"source_asset": {
"type": "object"
},
"content_resource": {
"type": "object"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
},
"credits_skipped_reason": {
"type": "string"
}
},
"additionalProperties": true
}