CreateTranscodeRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ffmpeg-micro-com/json-schema/ffmpeg-micro-com-create-transcode-request-schema.json",
  "title": "CreateTranscodeRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ffmpeg-micro-com-openapi.yaml#/components/schemas/CreateTranscodeRequest",
  "type": "object",
  "required": [
    "inputs",
    "outputFormat"
  ],
  "properties": {
    "inputs": {
      "type": "array",
      "description": "Array of input videos (single for transcode, multiple for composition)",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "GCS URL (gs://bucket/object) from presigned upload, or public HTTP(S) URL. Prefer gs:// to avoid egress charges.\n"
          }
        }
      }
    },
    "outputFormat": {
      "type": "string",
      "enum": [
        "mp4",
        "webm",
        "mov",
        "avi",
        "mp3",
        "m4a",
        "aac",
        "wav",
        "ogg",
        "opus",
        "flac",
        "jpeg",
        "jpg",
        "png",
        "gif",
        "webp"
      ],
      "description": "Output container format — video (mp4, webm, mov, avi), audio (mp3, m4a, aac, wav, ogg, opus, flac) or image (jpeg/jpg, png, gif, webp). Validation is case/alias-insensitive (`jpg` = `jpeg`), but the value is STORED VERBATIM and reads back exactly as submitted. webm output automatically uses VP9/Opus codecs in preset and default modes; you only need explicit `-c:v`/`-c:a` options when supplying raw options.\n"
    },
    "preset": {
      "type": "object",
      "description": "Simple mode - quality and resolution presets (ignored if options provided)",
      "properties": {
        "quality": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ],
          "description": "Maps to CRF values (high=18, medium=23, low=28)"
        },
        "resolution": {
          "type": "string",
          "enum": [
            "480p",
            "720p",
            "1080p",
            "4k"
          ],
          "description": "Output resolution preset"
        }
      }
    },
    "options": {
      "type": "array",
      "description": "Advanced mode - FFmpeg options or virtual options (overrides preset if both provided).\n**Virtual Options** (prefix with `@`): - `@text-overlay`: Add text overlay with auto word-wrap and styling\n**FFmpeg Options**: Only allowlisted flags accepted for security.\n",
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/VirtualOption"
          },
          {
            "$ref": "#/$defs/FFmpegOption"
          }
        ]
      }
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional caller-supplied metadata for cross-referencing jobs with external systems (for example an original filename or a source record ID). Must be a JSON object; serialized size is capped at 8192 bytes. Stored under the `user` key of the job's `metadata` field, so the submitted value is available at `metadata.user` when fetching or listing jobs, and is echoed as `metadata.user` in the create response.\n"
    }
  },
  "$defs": {
    "FFmpegOption": {
      "type": "object",
      "required": [
        "option",
        "argument"
      ],
      "properties": {
        "option": {
          "type": "string",
          "description": "FFmpeg flag (e.g., -c:v, -crf, -preset)"
        },
        "argument": {
          "type": "string",
          "description": "Flag value"
        }
      }
    },
    "TextOverlayConfig": {
      "type": "object",
      "required": [
        "text"
      ],
      "properties": {
        "text": {
          "type": "string",
          "description": "Text to display (use \\n for manual line breaks, or use charsPerLine for auto word-wrap)",
          "maxLength": 10000
        },
        "style": {
          "type": "object",
          "properties": {
            "charsPerLine": {
              "type": "integer",
              "description": "Auto word-wrap at this character width (default: no wrap)",
              "minimum": 5,
              "maximum": 100
            },
            "font": {
              "type": "string",
              "description": "Font name (default: Arial)"
            },
            "fontSize": {
              "type": "integer",
              "minimum": 12,
              "maximum": 200,
              "description": "Font size in pixels (default: 48)"
            },
            "lineSpacing": {
              "type": "integer",
              "description": "Space between lines in pixels (default: 10)",
              "minimum": 0,
              "maximum": 100
            },
            "fontColor": {
              "type": "string",
              "description": "Font color (default: white)"
            },
            "x": {
              "type": "string",
              "description": "X position FFmpeg expression (default: (w-text_w)/2 for center)"
            },
            "y": {
              "type": "string",
              "description": "Y position FFmpeg expression (default: (h-text_h)/2 for center)"
            },
            "boxBorderW": {
              "type": "integer",
              "description": "Box padding/border width in pixels (default: 20)",
              "minimum": 0,
              "maximum": 100
            }
          }
        }
      }
    },
    "VirtualOption": {
      "type": "object",
      "required": [
        "option",
        "argument"
      ],
      "properties": {
        "option": {
          "type": "string",
          "enum": [
            "@text-overlay"
          ],
          "description": "Virtual option name (prefixed with @)"
        },
        "argument": {
          "oneOf": [
            {
              "$ref": "#/$defs/TextOverlayConfig"
            }
          ],
          "description": "Configuration object for the virtual option"
        }
      }
    }
  }
}