Documentation

Render videos

Render a video with the Swiftia API

Render Video

This endpoint renders a final MP4 for a generated short.

Endpoint

POST /api/render

Brand Preset Selection

You now have two ways to apply brand presets:

  1. Explicit preset (recommended for per-render control): send brandPresetId in the render request.
  2. Automatic default preset: if brandPresetId is omitted, Swiftia applies your organization's active default brand preset (isDefault: true, isActive: true) when available.

Precedence Rules

For short-video renders (type omitted or type: "shortVideo"):

  1. If brandPresetId is provided and valid, it is used first.
  2. If no brandPresetId, and preset (built-in style preset) is provided, built-in preset is used.
  3. Otherwise, Swiftia uses default organization brand preset (if any), then platform defaults.
  4. Explicit options in your request still override preset-derived values field-by-field.

Validation Rules

  • brandPresetId must belong to the same organization as the render request.
  • If brandPresetId exists but isActive is false, the request is rejected.
  • Inactive explicit preset error: 400 with message "Selected brand preset is inactive".
  • Unknown or cross-organization preset error: 404 with message "Brand preset not found for this organization".

Request Body (Short Video)

{
  "id": "YOUR_JOB_ID",
  "target": "SHORT_ID",
  "brandPresetId": "org_branding_id_optional",
  "preset": "VIRAL",
  "size": {
    "width": 1920,
    "height": 1080,
    "name": "16:9"
  },
  "options": {
    "maxWordsInPage": 5,
    "waterMark": {
      "waterMarkUrl": "https://example.com/logo.png",
      "left": "100px",
      "top": "30px",
      "width": "400px",
      "blendMode": "normal",
      "opacity": "0.9"
    },
    "style": [
      {
        "property": "color",
        "value": "#ffffff",
        "active": { "value": "#00ff00", "duration": 0.2 },
        "past": { "value": "#888888", "duration": 0.5 }
      }
    ],
    "director": {
      "camera": { "facePaddingFactor": 3.5 },
      "intelligence": { "maxSpeakersToFocus": 1 }
    }
  }
}

Key Parameters

  • id (string, required): Completed VideoShorts job id.
  • target (string/number, required): Target short id from the job response.
  • brandPresetId (string, optional): Explicit organization brand preset id to apply for this render.
  • preset (string, optional): Built-in style preset (DEFAULT, VIRAL, etc.). If both are provided, brandPresetId wins.
  • size (object, optional): Requested output resolution.
  • options (object, optional): Render options (waterMark, style, director, maxWordsInPage).

Response

{
  "renderId": "NEWLY_CREATED_RENDER_ID"
}

Examples

1) Explicit brand preset (preferred)

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",
    "brandPresetId": "cmbp_12345"
  }'

2) Both brandPresetId and built-in preset

brandPresetId is applied, built-in preset is ignored for preset selection.

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",
    "brandPresetId": "cmbp_12345",
    "preset": "VIRAL"
  }'

3) Override specific values on top of selected brand preset

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",
    "brandPresetId": "cmbp_12345",
    "options": {
      "maxWordsInPage": 4
    }
  }'

Common Errors

400 - Inactive selected brand preset

{
  "message": "Selected brand preset is inactive"
}

404 - Brand preset not found in organization

{
  "message": "Brand preset not found for this organization"
}

403 - Plan restriction (resolution)

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