VideoEditRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beatra-ai/json-schema/beatra-ai-video-edit-request-schema.json",
  "title": "VideoEditRequest",
  "description": "Instruction-based video editing with optional multimodal references.",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beatra-ai-api-openapi.json#/components/schemas/VideoEditRequest",
  "properties": {
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Metadata",
      "description": "Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars"
    },
    "callback_url": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2048,
          "pattern": "^https://"
        },
        {
          "type": "null"
        }
      ],
      "title": "Callback Url",
      "description": "HTTPS URL beatra will POST the final Task envelope to when the Task reaches a terminal state"
    },
    "callback_signing_key_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 64,
          "minLength": 1,
          "pattern": "^whkey_[A-Za-z0-9]+$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Callback Signing Key Id",
      "description": "Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided."
    },
    "model": {
      "type": "string",
      "enum": [
        "auto",
        "wan3.0-video",
        "wan3.0-video-prime",
        "happyhorse-1.0-video-edit",
        "wan2.7-videoedit",
        "seedance-2",
        "seedance-2-fast",
        "seedance-2-mini",
        "seedance-2.5"
      ],
      "title": "Model",
      "description": "Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted.",
      "default": "auto"
    },
    "negative_prompt": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ],
      "title": "Negative Prompt",
      "description": "Content or qualities to avoid when supported by the selected model."
    },
    "duration": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "string",
          "const": "auto"
        },
        {
          "type": "null"
        }
      ],
      "title": "Duration",
      "description": "Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default."
    },
    "aspect_ratio": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "16:9",
            "9:16",
            "1:1",
            "4:3",
            "3:4",
            "4:5",
            "5:4",
            "21:9",
            "9:21",
            "adaptive"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Aspect Ratio",
      "description": "Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior."
    },
    "resolution": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "480p",
            "720p",
            "1080p",
            "2k",
            "4k"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Resolution",
      "description": "Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced."
    },
    "seed": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 2147483647.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Seed"
    },
    "enhance_prompt": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Enhance Prompt",
      "description": "Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written."
    },
    "watermark": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Watermark",
      "description": "Whether generated video should include the model watermark."
    },
    "generate_audio": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Generate Audio",
      "description": "Whether the selected model should generate synchronized audio."
    },
    "web_search": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Web Search",
      "description": "Whether the selected model may use web search during generation."
    },
    "return_last_frame": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Return Last Frame",
      "description": "Whether to return the generated video's last frame as an image artifact."
    },
    "output_format": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "mp4",
            "mov"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Output Format",
      "description": "Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding."
    },
    "source_video": {
      "oneOf": [
        {
          "$ref": "#/$defs/MediaInputUrl"
        },
        {
          "$ref": "#/$defs/MediaInputArtifact"
        },
        {
          "$ref": "#/$defs/MediaInputDataUri"
        }
      ],
      "title": "Source Video",
      "description": "Required video whose existing content will be edited."
    },
    "instruction": {
      "type": "string",
      "maxLength": 20000,
      "minLength": 1,
      "title": "Instruction",
      "description": "Required instruction describing changes to the source video."
    },
    "references": {
      "items": {
        "$ref": "#/$defs/VideoReference"
      },
      "type": "array",
      "maxItems": 49,
      "title": "References",
      "description": "Optional ordered image, video, or audio references. The selected model must support every supplied reference kind and count."
    },
    "audio_setting": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "auto",
            "origin"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Audio Setting",
      "description": "Optional edit-audio policy: auto lets a compatible model choose, while origin requests preservation of source audio."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "source_video",
    "instruction"
  ],
  "$defs": {
    "MediaInputArtifact": {
      "properties": {
        "type": {
          "type": "string",
          "const": "artifact",
          "title": "Type"
        },
        "artifact_id": {
          "type": "string",
          "title": "Artifact Id",
          "description": "ULID of a previously-uploaded artifact"
        }
      },
      "type": "object",
      "required": [
        "type",
        "artifact_id"
      ],
      "title": "MediaInputArtifact"
    },
    "MediaInputDataUri": {
      "properties": {
        "type": {
          "type": "string",
          "const": "data_uri",
          "title": "Type"
        },
        "data": {
          "type": "string",
          "maxLength": 262144,
          "title": "Data",
          "description": "Data URI (e.g. data:image/png;base64,...) — max 256KB encoded"
        }
      },
      "type": "object",
      "required": [
        "type",
        "data"
      ],
      "title": "MediaInputDataUri"
    },
    "MediaInputUrl": {
      "properties": {
        "type": {
          "type": "string",
          "const": "url",
          "title": "Type"
        },
        "url": {
          "type": "string",
          "title": "Url",
          "description": "HTTPS URL. External URLs are downloaded and re-hosted to beatra CDN."
        }
      },
      "type": "object",
      "required": [
        "type",
        "url"
      ],
      "title": "MediaInputUrl"
    },
    "VideoReference": {
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "image",
            "video",
            "audio"
          ],
          "title": "Kind",
          "description": "Declares whether this ordered reference is image, video, or audio."
        },
        "media": {
          "oneOf": [
            {
              "$ref": "#/$defs/MediaInputUrl"
            },
            {
              "$ref": "#/$defs/MediaInputArtifact"
            },
            {
              "$ref": "#/$defs/MediaInputDataUri"
            }
          ],
          "title": "Media",
          "description": "Artifact, HTTPS URL, or data URI for this ordered reference."
        },
        "role": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "subject",
                "style",
                "character",
                "product",
                "background",
                "pose"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Role",
          "description": "Optional semantic hint. Set it only when `beatra.models.list` advertises top-level `reference_roles` for the selected typed video model card; otherwise omit it and identify ordered references in the prompt."
        },
        "reference_voice": {
          "anyOf": [
            {
              "oneOf": [
                {
                  "$ref": "#/$defs/MediaInputUrl"
                },
                {
                  "$ref": "#/$defs/MediaInputArtifact"
                },
                {
                  "$ref": "#/$defs/MediaInputDataUri"
                }
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Reference Voice",
          "description": "Optional voice reference associated with this item when the selected model supports it."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "kind",
        "media"
      ],
      "title": "VideoReference",
      "description": "One ordered visual reference with optional semantic and voice guidance."
    }
  }
}