Video Effects (Virtual Options)

Video effects let you apply higher-level transformations—such as quote cards and text overlays—without crafting complex FFmpeg filter graphs. Each effect layers on top of your uploaded media and works alongside the standard options array.

Usage Overview
Add effects to the @options array when you create a transcode job. You can mix and match effects with regular FFmpeg flags or presets—they are processed in the order provided.
curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "inputs": [
      { "url": "gs://your-bucket/video.mp4" }
    ],
    "outputFormat": "mp4",
    "options": [
      {
        "option": "@text-overlay",
        "argument": {
          "text": "Hello world!",
          "style": { "position": "center", "fontSize": 60 }
        }
      }
    ]
  }'
@text-overlay
Add subtitle-style text overlays
Generates an ASS subtitle file on the fly so you can position, style, and wrap text without writing FFmpeg drawtext filters directly.
Required parameters
  • text — overlay contents (string)
Optional style parameters

Provide a style object to fine-tune appearance.

position

Preset anchor (e.g. "center", "top-left", "bottom-right")

x

Custom X expression (e.g. "0.15*w") — overrides preset positioning

y

Custom Y expression

fontSize

Number of points (defaults to 48)

fontColor

Hex color or ASS formatted color

outlineThickness

Stroke width in pixels

margin

Margin in pixels applied to all sides

textWidth

Max width in pixels before wrapping

Example request
{
  "inputs": [
    { "url": "gs://your-bucket/clip.mp4" }
  ],
  "outputFormat": "mp4",
  "options": [
    {
      "option": "@text-overlay",
      "argument": {
        "text": "If you're seeing this, the universe is telling you to set constraints.",
        "style": {
          "position": "center",
          "fontSize": 60,
          "outlineThickness": 20,
          "margin": 120
        }
      }
    }
  ]
}
@quote-card
Generate 1080×1080 quote cards
Builds a social-ready quote card with optional profile imagery and backgrounds using ASS subtitles and FFmpeg filters—no design tools required.
Required parameters
  • quote — primary quote text (string)
Optional parameters
name

Speaker name displayed beneath the quote

handle

Social handle or subtitle

profileImageUrl

HTTPS URL of profile image to render in a circle

backgroundUrl

HTTPS URL of background image/video; defaults to a black 1080 canvas

style.duration

Video length in seconds (default 5)

style.quoteFontSize

Font size for quote text

style.nameFontSize

Font size for speaker name

style.handleFontSize

Font size for handle text

style.textColor

Color for quote text

style.nameColor

Color for speaker name

style.handleColor

Color for handle text

style.fontFamily

ASS-compatible font family

style.profileSize

Diameter of profile circle (px)

style.profileMarginLeft

Left offset for profile circle

style.profileMarginTop

Top offset for profile circle

style.textMarginLeft

Left margin for quote text

style.quoteMarginLeft

Left inner margin for quote block

style.quoteMarginRight

Right inner margin for quote block

Example request
{
  "inputs": [
    { "url": "https://filesamples.com/samples/video/mp4/sample_640x360.mp4" }
  ],
  "outputFormat": "mp4",
  "options": [
    {
      "option": "@quote-card",
      "argument": {
        "quote": "Constraints create focus. Focus creates momentum.",
        "name": "Javid Jamae",
        "handle": "@deliveringgrowth",
        "profileImageUrl": "https://your-cdn.com/profile.jpg",
        "style": {
          "duration": 6,
          "profileSize": 180,
          "textMarginLeft": 360
        }
      }
    },
    { "option": "-crf", "argument": "28" },
    { "option": "-c:v", "argument": "libx264" },
    { "option": "-c:a", "argument": "copy" }
  ]
}
Tips & best practices
Keep these tips in mind when composing virtual options with traditional FFmpeg flags.
  • Prefer HTTPS URLs for profile and background assets, or use signed URLs with sufficient TTL.
  • Combine effects with standard FFmpeg options like -crf or -preset for fine-grained encoding control.
  • Quote card defaults to a 1080×1080 canvas—square imagery avoids unintended cropping.
  • Store frequently reused asset URLs in your own library so new jobs can reference them quickly.