Documentation

Render videos

Render a video with the Swiftia API

Render Video

This endpoint initiates the rendering process for a specific short generated by the VideoShorts function. Rendering creates the final video output (MP4) with captions, styles, and watermarks applied.

Brand Presets

If your organization has a default brand preset configured, it will be automatically applied to your render requests. Brand presets can include:

  • Video size/dimensions (for Pro and Swift plans)
  • Watermark settings (logo, position, opacity, etc.)
  • Caption styles (colors, animations, etc.)
  • Director/camera control settings (camera movement, speaker focus)

You can override any brand preset setting by explicitly providing the corresponding parameter in your render request. Brand presets are managed through the Brand Presets API or through the Swiftia Studio UI.

Endpoint

POST /api/render

Request Body

{
  "id": "YOUR_JOB_ID",
  "target": "SHORT_ID", // ID of the short to render
  "preset": "VIRAL", // Optional preset style
  "size": { // Optional custom video dimensions
    "width": 1920,
    "height": 1080,
    "name": "16:9"
  },
  "options": { // Optional rendering options
    "maxWordsInPage": 5,
    "waterMark": {
      "waterMarkUrl": "YOUR_WATERMARK_URL",
      "left": "100px",
      "top": "30px",
      "width": "400px",
      "blendMode": "normal",
      "opacity": "0.9"
    },
    "style": [
      {
        "property": "color",
        "value": "#ffffffed",
        "active": {
          "value": "#ff00cdff",
          "duration": 0.3
        },
        "past": {
          "value": "#ffffffed",
          "duration": 0.7
        }
      }
    ],
    "director": {
        "camera": {
            "facePaddingFactor": 3.5
        },
        "intelligence": {
            "maxSpeakersToFocus": 1
        }
    }
  }
}

Request Parameters

  • id (string, required): The ID of the completed VideoShorts job. This is the same id you received when creating the job. It is used to identify the specific job whose results you want to render.

  • target (string, required): The ID of the short to render. This ID corresponds to the id field within the shorts array in the Get Job response. It identifies the specific short video within the job's results that you want to render.

  • preset (string, optional): A predefined style preset to apply to the captions. Provides a quick way to apply pre-configured styles. If omitted, the default style is used. Available presets are: "DEFAULT", "GRAPES", "VIRAL", "BLURRY", "FAST", "DEEP DIVER", "GLOW VIOLET", "70S RADIATION", "BILL GREEN", "ETHEREAL UNDERLINE".

  • size (object, optional): Custom video dimensions for the rendered output. If omitted, uses the default resolution based on your plan or your organization's default brand preset (if set).

    • width (number, required if size is present): The width of the rendered video in pixels.
    • height (number, required if size is present): The height of the rendered video in pixels.
    • name (string, optional): A descriptive name for the format (e.g., "16:9", "9:16", "1:1").
    • Common Video Formats:
      • Portrait (9:16): Ideal for TikTok, YouTube Shorts, Instagram Reels. Example: 1080×1920
      • Landscape (16:9): Ideal for YouTube, Facebook videos. Example: 1920×1080
      • Square (1:1): Ideal for Instagram posts, Facebook posts. Example: 1080×1080
      • Additional formats like 4:3, 3:4, 21:9, 9:21, 5:4, and 4:5 are also supported for Pro and Swift plans.
    • Plan Restrictions:
      • Free and Starter plans: Limited to default portrait format only. Custom sizes must match your plan's default resolution.
      • Pro and Swift plans: Can choose between portrait, landscape, and square formats (and other formats) within plan limits (up to height × height from your plan's resolution).
      • Error handling: Requests with non-allowed resolutions will return a 403 Forbidden error with upgrade suggestions.
    • Brand Preset Integration: If your organization has a default brand preset with a size configured, and you don't provide a size in the request, the brand preset's size will be automatically applied (for Pro and Swift plans only).

  • options (object, optional): Additional rendering options for fine-grained customization.

    • maxWordsInPage (integer, optional): Controls the maximum number of words displayed on each caption page in the rendered video. Helps to control the reading pace for viewers.

    • waterMark (object, optional): Allows customization of the watermark. If omitted, the default Swiftia watermark (for free tier users), your organization's default brand preset watermark (if configured), or your uploaded watermark (for paid tier users) is used.

      • Watermark Behavior: The watermark behavior depends on your Swiftia subscription tier:
        • Free Tier: A default Swiftia watermark is applied to rendered videos. You cannot customize or remove this watermark. The waterMarkUrl parameter is not applicable for free tier users. Any waterMark options provided in the request will be ignored.
        • Paid Tiers: You can customize the watermark by providing the waterMarkUrl parameter with a URL to your own watermark image. You can also customize the position, size, opacity, and blend mode of the watermark using the options within the waterMark object. If you do not provide the waterMark object, your organization's default brand preset watermark (if set) or your default uploaded watermark (configured in your account settings) will be used.
      • waterMarkUrl (string, required if waterMark is present, paid tiers only): The URL of a custom watermark image. Allows paid users to replace the default Swiftia watermark with their own branding.
      • left (string, required if waterMark is present): Horizontal position of the watermark. Must be specified in pixels (px), e.g., "100px", "calc(100% - 430px)".
      • top (string, required if waterMark is present): Vertical position of the watermark from the top edge of the video. Must be specified in pixels (px), e.g., "30px", "80px".
      • width (string, optional): Width of the watermark. Must be specified in pixels (px), e.g., "400px", "200px".
      • blendMode (string, optional): Blend mode for the watermark. Valid values: "normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity". Controls how the watermark blends with the underlying video. Defaults to "normal".
      • opacity (string, required if waterMark is present): Opacity of the watermark (0.0 - 1.0). Allows control over the watermark's visibility.
      • width (string, required if waterMark is present): Width of the watermark. The height is scaled proportionally.

    • style (array, optional): An array of style objects for detailed caption styling. Each object allows you to customize individual CSS properties and their behavior during the video.

      • property (string, required): The CSS property to modify (e.g., "color", "font-size", "text-shadow", etc.). Supports a wide range of CSS properties for flexible styling.
      • value (string, required): The default value for the CSS property. This is the base style applied to the captions.
      • active (object, optional): Defines the style applied when a word is being spoken in the video. This allows for dynamic highlighting of the current word.
        • value (string, required): The value for the CSS property in the active state.
        • duration (number, optional): The duration of the transition to the active state in seconds. Provides smooth animation.
      • past (object, optional): Defines the style applied after a word has been spoken. This allows for visual distinction between spoken and upcoming words.
        • value (string, required): The value for the CSS property in the past state.
        • duration (number, optional): The duration of the transition to the past state in seconds. Provides smooth animation.

    • director (object, optional): Provides advanced control over the AI Director (speaker focus) feature. If omitted, default values will be used or values from your organization's default brand preset (if configured). This option is only applicable for shorts that have Active Speaker Detection (ASD) data. Note: This feature is available in the API and allows paid organizations to control camera movement and the number of focused talking persons in videos.

      • camera (object): Controls camera behavior.
        ParameterTypeDescriptionDefault
        facePaddingFactornumberControls padding around faces. Higher is wider.1.7
        maxZoomFactornumberPrevents excessive zooming. 0.5 = 2x max zoom.0.5
        zoomSafeZoneFactornumberMinimum change (relative to face size) required before zoom updates. Prevents jitter.0.2
        smoothingFactornumberControls camera smoothness. Lower is smoother.0.03
        predictionFramesnumberFrames to analyze for predictive movement.10
        predictionWeightnumberHow much future movement to apply.0.1
        movementThresholdFactornumber"Dead zone" to prevent jitter. Factor of video width.0.02
      • layout (object): Controls layout transitions.
        ParameterTypeDescriptionDefault
        minIndicatorDurationFramesnumberMinimum time a layout must be active. Prevents flickering.15
        speakerLingerFramesnumberHow long to hold on a speaker after they stop talking.0
      • intelligence (object): Controls the AI decision-making.
        ParameterTypeDescriptionDefault
        focusSpeakingScoreThresholdnumberScore to be considered an active speaker.-10
        maxSpeakersToFocusnumberMax speakers in a grid layout.1
        disableFocusThresholdnumberDisables focus when this many faces are detected. Forces wide shot.7
        speakerDominanceWindowFramesnumberFrames to average for speaker dominance. Higher is more stable.30
      • overlaysAndTiming (object): Controls debug overlays and synchronization.
        ParameterTypeDescriptionDefault
        showFaceBoundingBoxesbooleanEnables visualization of face detection boxes and speaking scores.false
        asdFrameOffsetnumberSynchronizes ASD data with video.0

Response

{
  "renderId": "NEWLY_CREATED_RENDER_ID"
}

Response Parameters

  • renderId (string): The unique identifier for the render job. Use this ID with the GET /api/render/[renderId] endpoint to retrieve the render status and, upon completion, the URL of the rendered video.

Example

Example Request (cURL)

curl --request POST \
  --url https://app.swiftia.io/api/render \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "cm3xgztna0001p2j74vvf8i72",
    "target": "SHORT_ID",
    "preset": "VIRAL",
    "options": {
      "maxWordsInPage": 5,
      "waterMark": {
        "waterMarkUrl": "https://your-watermark-url.com/logo.png",
        "left": "10px",
        "top": "20px",
        "opacity": "0.8",
        "width": "100px"
      },
      "style": [
        {
          "property": "color",
          "value": "#ffffff",
          "active": {
            "value": "#00ff00",
            "duration": 0.2
          },
          "past": {
            "value": "#888888",
            "duration": 0.5
          }
        }
      ]
    }
  }'

Example Response

{
  "renderId": "y9x9kjinh2"  // Example renderId
}

Error Responses

403 Forbidden - Plan Restriction

When requesting a custom video size that's not allowed for your plan:

{
  "message": "Only the default portrait format (720×1280) is available for free plans. Upgrade to Pro or Swift to access all video formats."
}

Common scenarios:

  • Free/Starter plans requesting non-default resolutions
  • Custom dimensions exceeding plan limits
  • Invalid size parameters that don't match plan restrictions

400 Bad Request - Invalid Size

When providing invalid size parameters:

{
  "message": "Resolution 1920x1080 exceeds plan maximum resolution of 1280x1280"
}

Common scenarios:

  • Dimensions too large for your plan's maximum resolution
  • Invalid size format or missing required parameters
  • Unsupported aspect ratios for your plan tier