ImageToVideoRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beatra-ai/json-schema/beatra-ai-image-to-video-request-schema.json",
  "title": "ImageToVideoRequest",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beatra-ai-api-openapi.json#/components/schemas/ImageToVideoRequest",
  "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",
        "minimax-h3",
        "wan3.0-video",
        "wan3.0-video-prime",
        "happyhorse-1.1-i2v",
        "wan2.7-i2v",
        "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."
    },
    "prompt": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 20000
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompt",
      "description": "Optional motion, scene, and camera instructions for animating the opening image."
    },
    "image": {
      "oneOf": [
        {
          "$ref": "#/$defs/MediaInputUrl"
        },
        {
          "$ref": "#/$defs/MediaInputArtifact"
        },
        {
          "$ref": "#/$defs/MediaInputDataUri"
        }
      ],
      "title": "Image",
      "description": "Required strict first-frame image; this is not a loose visual reference."
    },
    "driving_audio": {
      "anyOf": [
        {
          "oneOf": [
            {
              "$ref": "#/$defs/MediaInputUrl"
            },
            {
              "$ref": "#/$defs/MediaInputArtifact"
            },
            {
              "$ref": "#/$defs/MediaInputDataUri"
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Driving Audio",
      "description": "Optional driving audio. Supplying it requires a model that supports this control."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "image"
  ],
  "$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"
    }
  }
}