Archived docs Get your API Key
Documentation
🤖 AI Assistant

Image element

Type: object

Defines an image element to be included in the video. The image source can be specified using a URL, supporting common image formats like JPG, PNG, and GIF, or generated using AI from a text prompt. This element supports properties for visual positioning and sizing.

Working with the Image element

Using image files

To include an image in your video, you need to provide a direct URL to a file in a common format such as JPEG or PNG. This URL should be assigned to the src property and must be publicly accessible to ensure the image loads correctly during video rendering.

If the image is hosted on a restricted server or requires authentication, it may not be retrievable by JSON2Video. Ensure that the URL is valid and does not require login credentials.

Example

This example creates an horizontal video showing an image (flower-bee.jpg) during 10 seconds.

{
  "resolution": "full-hd",
  "scenes": [
    {
      "elements": [
        {
          "type": "image",
          "src": "https://cdn.json2video.com/assets/images/flower-bee.jpg",
          "duration": 10
        }
      ]
    }
  ]
}

Google Drive and Dropbox

JSON2Video also supports images stored in Google Drive and Dropbox, but they must be set to public access. If the file is private or requires special permissions, the system will be unable to fetch it for video creation.

Generating AI images dynamically

In addition to using pre-existing image files, JSON2Video allows you to generate AI images dynamically using text prompts. This is useful when you don't have access to stock images or need visuals that match specific content, such as a voiceover or theme.

Currently, JSON2Video supports AI image generation using models from different providers. The available models include:

  • Flux Pro (flux-pro) – Designed for generating high-quality, realistic images.
  • Freepik Classic (freepik-classic) – Provides visually appealing digital artwork and illustrations.

Since AI-generated images require additional processing, they may consume extra credits. For more details, refer to Credits Consumption.

Example

This example creates a vertical video with an AI generated image that fills the full video canvas.

{
  "resolution": "custom",
  "width": 1080,
  "height": 1920,
  "scenes": [
    {
      "elements": [
        {
          "type": "image",
          "model": "freepik-classic",
          "prompt": "A stunning sunset over a calm ocean, with vibrant orange, pink, and purple hues reflecting on the water.",
          "aspect-ratio": "vertical",
          "resize": "fill",
          "duration": 10
        }
      ]
    }
  ]
}

By leveraging AI image generation, you can dynamically create unique and context-relevant visuals without relying on external image sources.

Properties

aspect-ratio

Defines the aspect ratio of the content generated by the AI model. This property allows you to specify the desired shape of the content, with options for horizontal (wide), vertical (tall), and squared (equal width and height). The default value is horizontal.
Type string
Required No
Default Value "horizontal"
Enum Values horizontal, vertical, squared

cache

If true, the system will attempt to retrieve and use a previously rendered (cached) version of this element, if an identical version is available. This can significantly reduce processing time. If false, a new render of the element will always be performed, regardless of whether a cached version exists. The default value is true.
Type boolean
Required No
Default Value true
Format boolean

chroma-key

Allows you to define a color or a range of colors within the element that will be rendered as transparent. This effect is commonly known as chroma keying or 'green screen'. The color property specifies the base color to be made transparent, while the optional tolerance property adjusts the sensitivity of the transparency, allowing you to define a range of similar colors to also be included in the transparency effect.
Type object
Required No

This object contains the following properties:

  • color: (string, required) - Set the color for which alpha will be set to 0 (full transparency)

    • Example: "#00b140"

  • tolerance: (integer, optional) - Makes the selection more or less sensitive to changes in color. A value of 1 will select only the provided color. A value of 100 will select all colors, so the full canvas

    • Default: 25
    • Minimum: 1
    • Maximum: 100

comment

A field for adding descriptive notes or internal memos related to the element. This comment is for your reference and does not affect the rendering process. It can be used to keep notes about the element like describing the content or the purpose of the element.
Type string
Required No

condition

A string containing an expression that determines whether the element will be rendered. The element is rendered only if the condition evaluates to true. If the condition is false or an empty string, the element will be skipped and not included in the scene or movie.
Type string
Required No

connection

The ID of a pre-configured connection to use for generating the asset. Connections are defined from the Dashboard. Specifying a connection ID allows you to use your own account's API key in the AI model provider (for example, your own account on Replicate or Freepik). If no connection ID is provided, the default JSON2Video's API keys will be used, which may deduct credits for the API calls.
Type string
Required No

correction

Defines image and video correction settings, allowing you to adjust the visual characteristics of the element. This includes properties for adjusting contrast, brightness, saturation, and gamma, enabling fine-tuning of the element's appearance. Values in the edge of the range may result in the element being irrecognizable.
Type object
Required No

This object contains the following properties:

  • brightness: (number, optional) - Adjust the brightness

    • Default: 0
    • Minimum: -1
    • Maximum: 1

  • contrast: (number, optional) - Adjust the contrast

    • Default: 1
    • Minimum: -1000
    • Maximum: 1000

  • gamma: (number, optional) - Adjust the gamma

    • Default: 1
    • Minimum: 0.1
    • Maximum: 10

  • saturation: (number, optional) - Adjust the saturation

    • Default: 1
    • Minimum: 0
    • Maximum: 3

crop

Defines the cropping area of the element. It allows you to specify a rectangular region of the element to display, effectively cropping the external parts of the provided area. The x and y properties define the top-left corner of the cropping rectangle, while the width and height properties determine the dimensions of the cropped area.
Type object
Required No

This object contains the following properties:

  • height: (integer, required) - Sets the height of the cropping area

  • width: (integer, required) - Sets the width of the cropping area

  • x: (integer, optional) - Sets the left point of cropping

    • Default: 0

  • y: (integer, optional) - Sets the top point of cropping

    • Default: 0

duration

Defines the duration of the element in seconds. Use a positive value to specify the element's length. A value of -1 instructs the system to automatically set the duration based on the intrinsic length of the asset or file used by the element. A value of -2 sets the element's duration to match that of its parent scene (if it's inside a scene) or the movie (if it's in the movie elements array).
Type number
Required No
Default Value -1
Format float

extra-time

The amount of time, in seconds, to extend the element's duration beyond its natural length. This allows the element to linger on screen after its content has finished playing or displaying. For example, setting extra-time to 0.5 will keep the element visible for an additional half-second.
Type number
Required No
Default Value 0
Format float

fade-in

The duration, in seconds, of the fade-in effect applied to the element's appearance. A value of 0 means no fade-in effect. Larger values result in a longer fade-in duration. The value must be a non-negative number.
Type number
Required No
Format float
Minimum Value 0

fade-out

The duration, in seconds, of the fade-out effect applied to the element's disappearance. A value of 0 means no fade-out effect. Larger values result in a longer fade-out duration. The value must be a non-negative number.
Type number
Required No
Format float
Minimum Value 0

flip-horizontal

If true, the element will be flipped horizontally, creating a mirror image effect. The default value is false.
Type boolean
Required No
Default Value false

flip-vertical

If true, the element will be flipped vertically, creating an upside-down image. The default value is false.
Type boolean
Required No
Default Value false

height

Sets the height of the element in pixels, scaling the element up or down as needed to fit the specified height. A value of -1 maintains the element's original aspect ratio when resizing based on the width property. If 'resize' is set, the 'height' property is ignored. The minimum accepted value is -1.
Type integer
Required No
Default Value -1
Minimum Value -1

id

A unique identifier for the element within the movie. This string allows you to reference and manage individual elements. If not provided, the system will automatically generate a random string.
Type string
Required No
Default Value "@randomString"

mask

URL to a PNG or video file that defines a mask, controlling the transparency of the element. The mask uses a grayscale color scheme: black areas render the element fully transparent, white areas render it fully opaque, and shades of gray create varying levels of partial transparency. This allows you to create complex shapes and effects by selectively hiding portions of the element.
Type string
Required No

model

The generative AI model to use. Refer to the documentation above to see a list of available models. The selected model will be used to generate the asset with AI.
Type string
Required No

model-settings

A set of optional settings specific to the chosen generative AI model. These settings allow you to fine-tune the asset generation process and are passed directly to the underlying AI model. The available settings will vary depending on the model selected and are detailed in the model's documentation.
Type object
Required No

pan

Specifies the direction to pan the element within its container. Valid values are left, top, right, bottom, and their combinations like top-left. If the zoom property is also specified, the pan will occur while zooming. If zoom is not specified, the element will pan without zooming.
Type string
Required No
Enum Values left, top, right, bottom, top-left, top-right, bottom-left, bottom-right

pan-crop

When panning an element, this boolean property determines whether the element is stretched and cropped to fill the movie canvas. If set to true (default), the element will be stretched and cropped during panning. If set to false, the element will not be stretched and potentially leave empty space within the movie canvas. Example: if pan-crop is set to false and the movie canvas and element have the same size, panning the element to the left may leave a black bar on the right side of the movie canvas as the element moves to the left. If pan-crop is set to true (default), the element will be stretched and cropped during panning, so the element will effectively fill the movie canvas.
Type boolean
Required No
Default Value true

pan-distance

Defines the distance the element pans within its container when the pan property is specified. This value, expressed as a floating-point number, determines the amount of movement during the panning effect. Higher values result in faster and more pronounced panning. The allowed range is from 0.01 to 0.5, with a default value of 0.1.
Type number
Required No
Default Value 0.1
Format float
Minimum Value 0.01
Maximum Value 0.5

position

Specifies the position of the element within the movie canvas. Choose from predefined positions like 'top-left', 'top-right', 'bottom-right', 'bottom-left', and 'center-center' to quickly place the element. Selecting 'custom' enables precise positioning using the x and y properties to define the element's horizontal and vertical coordinates.
Type string
Required No
Default Value "custom"
Enum Values top-left, top-right, bottom-right, bottom-left, center-center, custom

prompt

The text prompt that guides the generative AI model in creating the desired asset. This prompt should clearly and concisely describe the type of content you want the model to generate. The quality and specificity of the prompt directly influence the output of the AI model.
Type string
Required No

resize

Defines how the element should be resized to fit within the movie canvas. The values cover and fill stretch the element to completely cover the movie canvas, potentially cropping parts of the element. The values fit and contain ensure the entire element is visible, potentially leaving empty space within the canvas. When resize is set, the width and height properties are ignored, as the element's size is determined by the chosen resize mode. The value coveris a synonym for fill and containis a synonym for fit.
Type string
Required No
Enum Values cover, fill, fit, contain

rotate

Defines the rotation properties of the element. It allows you to specify the angle of rotation and the time it takes to complete the rotation, enabling animated rotation effects.
Type object
Required No

This object contains the following properties:

  • angle: (number, required) - Sets the angle of rotation

    • Default: 0
    • Minimum: -360
    • Maximum: 360

  • speed: (number, optional) - Sets the time it takes to rotate the provided angle. A zero value means no movement

    • Default: 0
    • Minimum: 0

src

The URL to the image asset file. This should be a publicly accessible URL pointing to the image file, which can be in JPG, PNG, GIF, or any other common image format.
Type string
Required No
Format uri

start

The element's start time, in seconds, determines when it begins playing within its container's timeline. This time is relative to the beginning of the scene it's in or, if the element is part of the movie's elements array, relative to the beginning of the movie itself. The default value is 0, meaning the element starts at the beginning of its container's timeline.
Type number
Required No
Default Value 0
Format float

type

This field specifies the element's type and must be set to image for image elements.
Type string
Required No
Enum Values image

variables

Defines local variables specific to this element. These variables can be used to dynamically alter the element's properties or content during the rendering process. Variable names must consist of only letters, numbers, and underscores.
Type object
Required No
Default Value {}

width

Sets the width of the element in pixels. The element will be scaled up or down to fit the specified width. A value of -1 instructs the system to maintain the element's original aspect ratio when resizing based on the height property. If 'resize' is set, the 'width' property is ignored. The minimum accepted value is -1.
Type integer
Required No
Default Value -1
Minimum Value -1

x

The horizontal position of the element within the movie canvas, measured in pixels. This property is only applicable when the position property is set to custom. A value of 0 places the element at the left edge of the movie canvas. Higher integer values move the element to the right.
Type number
Required No
Default Value 0
Format integer

y

Sets the vertical position of the element within the movie canvas, measured in pixels. This property is only applicable when the position property is set to custom. A value of 0 places the element at the top edge of the movie canvas. Higher integer values move the element downwards.
Type number
Required No
Default Value 0
Format integer

z-index

Element's z-index, determining its stacking order within the video. Higher values bring the element to the front, obscuring elements with lower values. Lower values send the element to the back, potentially behind other elements. The value must be an integer between -99 and 99; the default is 0. The natural way of layering elements is by the order of the elements in the elements array. If by any reason this does not work in your case, you can use the z-index property to manually control the stacking order.
Type number
Required No
Default Value 0
Format integer
Minimum Value -99
Maximum Value 99

zoom

Zooms the element by a specified percentage. Use positive values (1-10) to zoom in and negative values (-1 to -10) to zoom out. A value of 0 results in no zoom. Combine with the pan property to control the focal point during zooming.
Type integer
Required No
Minimum Value -10
Maximum Value 10

Examples

Example 1: Simple Image Element

This example demonstrates a movie with three images displayed in a slideshow. Each image is displayed for 3 seconds with a zoom effect and a pan effect.

{
  "resolution": "full-hd",
  "scenes": [
    {
      "comment": "First scene",
      "duration": 3,
      "elements": [
        {
          "type": "image",
          "src": "https://cdn.json2video.com/assets/images/london-01.jpg",
          "zoom": 3,
          "pan": "right"
        }
      ]
    },
    {
      "comment": "Second scene",
      "duration": 3,
      "elements": [
        {
          "type": "image",
          "src": "https://cdn.json2video.com/assets/images/london-02.jpg",
          "zoom": -3,
          "pan": "left"
        }
      ]
    },
    {
      "comment": "Third scene",
      "duration": 3,
      "elements": [
        {
          "type": "image",
          "src": "https://cdn.json2video.com/assets/images/london-03.jpg",
          "zoom": 3,
          "pan": "top"
        }
      ]
    }
  ]
}

Example 2: Image with Scaling and Rotation

This example shows how to scale an image and rotate it.

{
  "scenes": [
    {
      "elements": [
        {
          "type": "image",
          "src": "https://assets.json2video.com/assets/images/sunglasses-emoji-small.png",
          "x": 835,
          "y": 575,
          "width": 250,
          "height": 250,
          "rotate": {
            "angle": 360,
            "speed": 1
          }
        }
      ]
    }
  ]
}
← Previous: ElementNext: Video →