Documentation

Brand Presets

Manage brand presets with the Swiftia API

Brand Presets

Brand presets allow you to save and reuse your video rendering configurations, including video size, watermark settings, caption styles, and camera control options. When you set a brand preset as default, it will be automatically applied to all your render requests, ensuring consistent branding across your videos.

Overview

Brand presets are organization-specific and can include:

  • Video Size/Dimensions: Pre-configured video resolutions (portrait, landscape, square) for Pro and Swift plans
  • Watermark Settings: Logo URL, position (in pixels), size (in pixels), opacity, and blend mode. Note: The left, top, and width values must be specified in pixels (px), e.g., "100px".
  • Caption Styles: Colors, animations, and text styling
  • Director/Camera Control: Camera movement and speaker focus settings
  • Max Words Per Page: Control over caption display density

Endpoints

List Brand Presets

Get all brand presets for your organization.

Endpoint: GET /api/organizations/brandings

Note: When using API key authentication, the API automatically uses the organization associated with your API key. When using session-based authentication, you must include organizationId as a query parameter.

Headers:

Authorization: Bearer YOUR_API_KEY

Response:

[
  {
    "id": "branding_id",
    "name": "My Brand Preset",
    "description": "Default branding for social media",
    "preset": "VIRAL",
    "size": {
      "width": 1080,
      "height": 1920,
      "name": "9:16"
    },
    "options": {
      "maxWordsInPage": 5,
      "waterMark": {
        "waterMarkUrl": "https://example.com/logo.png",
        "left": "10px",
        "top": "20px",
        "opacity": "0.8",
        "width": "100px"
      },
      "style": [...],
      "director": {...}
    },
    "isActive": true,
    "isDefault": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

Create Brand Preset

Create a new brand preset for your organization.

Endpoint: POST /api/organizations/brandings

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body (with API key - organizationId not needed):

{
  "name": "My Brand Preset",
  "description": "Default branding for social media",
  "preset": "VIRAL",
  "size": {
    "width": 1080,
    "height": 1920,
    "name": "9:16"
  },
  "options": {
    "maxWordsInPage": 5,
    "waterMark": {
      "waterMarkUrl": "https://example.com/logo.png",
      "left": "10px",
      "top": "20px",
      "opacity": "0.8",
      "width": "100px"
    },
    "style": [
      {
        "property": "color",
        "value": "#ffffff",
        "active": {
          "value": "#00ff00",
          "duration": 0.2
        }
      }
    ],
    "director": {
      "camera": {
        "facePaddingFactor": 3.5
      },
      "intelligence": {
        "maxSpeakersToFocus": 1
      }
    }
  },
  "isDefault": true
}

Request Parameters:

  • organizationId (string, optional when using API key, required for session-based auth): Your organization ID. When using API key authentication, omit this parameter as the API automatically uses the organization associated with your API key. When using session-based authentication, this parameter is required.
  • name (string, required): Name of the brand preset.
  • description (string, optional): Description of the brand preset.
  • preset (string, optional): A predefined style preset name (e.g., "VIRAL", "DEFAULT"). If provided, it will be used as a base for the brand preset.
  • size (object, optional): Video dimensions. Only applicable for Pro and Swift plans.
    • width (number): Video width in pixels.
    • height (number): Video height in pixels.
    • name (string, optional): Format name (e.g., "9:16", "16:9", "1:1").
  • options (object, optional): Rendering options (same structure as render request options).
    • maxWordsInPage (integer, optional): Maximum words per caption page.
    • waterMark (object, optional): Watermark configuration.
      • waterMarkUrl (string, required): URL of the watermark/logo image.
      • left (string, optional): Horizontal position of the watermark. Must be specified in pixels (px), e.g., "100px".
      • top (string, optional): Vertical position of the watermark. 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".
      • opacity (string, optional): Opacity of the watermark (0.0 to 1.0), e.g., "0.9".
      • 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". Default: "normal".
    • style (array, optional): Caption styling options.
    • director (object, optional): Camera control and speaker focus settings.
  • isDefault (boolean, optional): Set to true to make this the default brand preset. Only one default preset is allowed per organization.

Response:

{
  "id": "branding_id",
  "name": "My Brand Preset",
  "description": "Default branding for social media",
  "preset": "VIRAL",
  "size": {
    "width": 1080,
    "height": 1920,
    "name": "9:16"
  },
  "options": {...},
  "isActive": true,
  "isDefault": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Update Brand Preset

Update an existing brand preset.

Endpoint: PUT /api/organizations/brandings/:id

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body:

{
  "name": "Updated Brand Preset",
  "isDefault": true,
  "isActive": true
}

Request Parameters:

All parameters are optional. Only include the fields you want to update.

  • organizationId (string, optional when using API key, required for session-based auth): Your organization ID. When using API key authentication, omit this parameter as the API automatically uses the organization associated with your API key. When using session-based authentication, this parameter is required.
  • name (string, optional): Updated name.
  • description (string, optional): Updated description.
  • preset (string, optional): Updated preset name.
  • size (object, optional): Updated video dimensions.
  • options (object, optional): Updated rendering options.
  • isDefault (boolean, optional): Set to true to make this the default preset.
  • isActive (boolean, optional): Set to false to deactivate the preset.

Response:

{
  "id": "branding_id",
  "name": "Updated Brand Preset",
  ...
}

Delete Brand Preset

Delete a brand preset.

Endpoint: DELETE /api/organizations/brandings/:id

Note: When using API key authentication, the API automatically uses the organization associated with your API key. When using session-based authentication, you must include organizationId as a query parameter.

Headers:

Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "message": "Brand preset deleted successfully"
}

Default Brand Presets

When you set a brand preset as default (isDefault: true), it will be automatically applied to all render requests for your organization. This means:

  1. Video Size: If your default brand preset has a size configured, and you don't provide a size in your render request, the brand preset's size will be used (Pro and Swift plans only).

  2. Watermark: If you don't provide waterMark options in your render request, your default brand preset's watermark settings will be used.

  3. Caption Styles: If you don't provide style options in your render request, your default brand preset's styles will be used.

  4. Director Settings: If you don't provide director options in your render request, your default brand preset's director settings will be used.

  5. Max Words Per Page: If you don't provide maxWordsInPage in your render request, your default brand preset's value will be used.

Note: You can always override any brand preset setting by explicitly providing the corresponding parameter in your render request.

Plan Restrictions

  • Free and Starter plans: Cannot set custom video sizes in brand presets. Only default portrait format is available.
  • Pro and Swift plans: Can set any video format (portrait, landscape, square) within plan limits in brand presets.

Example: Complete Workflow

1. Create a Brand Preset

With API Key (organizationId optional):

curl --request POST \
  --url https://app.swiftia.io/api/organizations/brandings \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Social Media Brand",
    "size": {
      "width": 1080,
      "height": 1920,
      "name": "9:16"
    },
    "options": {
      "waterMark": {
        "waterMarkUrl": "https://example.com/logo.png",
        "left": "10px",
        "top": "20px",
        "opacity": "0.8",
        "width": "100px"
      }
    },
    "isDefault": true
  }'

Without API Key (organizationId required):

curl --request POST \
  --url https://app.swiftia.io/api/organizations/brandings \
  --header 'Authorization: Bearer YOUR_SESSION_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "organizationId": "YOUR_ORG_ID",
    "name": "Social Media Brand",
    "size": {
      "width": 1080,
      "height": 1920,
      "name": "9:16"
    },
    "options": {
      "waterMark": {
        "waterMarkUrl": "https://example.com/logo.png",
        "left": "10px",
        "top": "20px",
        "opacity": "0.8",
        "width": "100px"
      }
    },
    "isDefault": true
  }'

2. Render with Default Brand Preset

When you render a video without specifying size or watermark, your default brand preset will be automatically applied:

curl --request POST \
  --url https://app.swiftia.io/api/render \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "YOUR_JOB_ID",
    "target": "SHORT_ID"
  }'

3. Override Brand Preset Settings

You can override specific brand preset settings in your render request:

curl --request POST \
  --url https://app.swiftia.io/api/render \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "YOUR_JOB_ID",
    "target": "SHORT_ID",
    "size": {
      "width": 1920,
      "height": 1080,
      "name": "16:9"
    }
  }'

In this example, the video will use the landscape format (16:9) instead of the brand preset's portrait format, but all other brand preset settings (watermark, styles, etc.) will still be applied.