Add Clip

Creates Clips from source media. Use when you want Storyteller to ingest a media URL and create a Clip with optional categories, collections, thumbnail, and action links.

All Clips created from the workflow will have their status set to Published.

• Workflow ID: add-clip

Basic Usage

Minimal Example Request

{
    "workflows": [
        "add-clip"
    ],
    "mediaUrls": [
        "https://cdn.example.com/videos/highlight-001.mp4"
    ],
    "metadata": {
        "https://cdn.example.com/videos/highlight-001.mp4": {
            "Title": "Derby Day Highlight"
        }
    }
}

Required Metadata

Key	Type	Required	Remarks
Title	string	Yes	Per-media. Clip title used internally.

Minimal Example Request with Optional Metadata

{
    "workflows": [
        "add-clip"
    ],
    "mediaUrls": [
        "https://cdn.example.com/videos/highlight-001.mp4"
    ],
    "metadata": {
        "https://cdn.example.com/videos/highlight-001.mp4": {
            "Title": "Derby Day Highlight",
            "DisplayTitle": "Highlight",
            "CreationTime": "2025-10-26T11:41:15+00:00"
        }
    }
}

Optional Basic Metadata

Key	Type	Required	Remarks
DisplayTitle	string	No	Per-media. Display title shown for the clip. If not provided, defaults to Title.
CreationTime	DateTime	No	Per-media. ISO 8601 creation time; defaults to current time if omitted.

cURL Example (Basic)

curl -X POST "https://integrations.usestoryteller.com/api/workflows/execute" \
  -H "x-storyteller-api-key: $ST_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "DisplayTitle": "Derby Day: 90s Highlight"
    }
  }
}
JSON

Advanced Usage

Clips can be created with additional metadata to set up more properties to work with optional categories, collections, thumbnail, and action links.

External Identifiers

Track clips using your own external identifier system:

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "ExternalId": "ext-clip-001"
    }
  }
}

Metadata:

Key	Type	Remarks
ExternalId	string	External identifier for the clip asset that can be used for future reference.

Action Links

Associate primary and secondary action links with clips:

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "PrimaryActionLinkId": "987ce210-0f79-404b-bd0a-5d6e67b58d3c",
      "SecondaryActionLinkIds": [
        "6df128ea-8aaa-4160-ae6e-382c1bf9727f",
        "d78234c3-16f7-4883-b499-14eeaacd87b8"
      ]
    }
  }
}

Metadata:

Key	Type	Remarks
PrimaryActionLinkId	Guid	Primary action link associated with the clip. Must be a valid GUID of an existing action link.
SecondaryActionLinkIds	ArrayOf(Guid)	Additional action links. Each must be a valid GUID of an existing action link.

Categories

Using Existing Categories (by External ID)

Both CategoryIds and Categories can be used to specify categories by their External IDs.

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "CategoryIds": ["premier-league", "featured"]
    }
  }
}

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "Categories": [
        {
          "ExternalId": "premier-league"
        },
        {
          "ExternalId": "featured"
        }
      ]
    }
  }
}

Creating New Categories

To create a new category all of it's properties must be specified in Categories:

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "Categories": [
        {
          "ExternalId": "premier-league",
          "DisplayTitle": "Premier League",
          "InternalTitle": "PL",
          "AvailableForNavigation": true,
          "ShowInClips": false,
          "Type": "Other"
        }
      ]
    }
  }
}

When creating a new category the following must be true:

• ExternalId is required and must be unique
• InternalTitle will default to ExternalId if not provided, but must be unique in the system
• DisplayTitle is optional (defaults to InternalTitle if not provided)
• ShowInClips must be set to false

Metadata:

Key	Type	Remarks
CategoryIds	ArrayOf(string)	Category external IDs to associate with the clip. Categories must already exist.
Categories	ArrayOf(object)	Rich category objects for creating or referencing categories.

Category Object Properties:

Property	Type	Required	Remarks
ExternalId	string	Yes	Unique external identifier for the category.
DisplayTitle	string	No	Display title shown to users.
InternalTitle	string	No	Internal title for CMS use. Defaults to ExternalId if not provided.
AvailableForNavigation	bool	No	Whether category appears in navigation. Defaults to false.
ShowInClips	bool	No	Whether category is shown in clips list. Defaults to false. Currently only false is supported.
Type	string	No	Category type (e.g., "Other", "Player").

Collections

Using Existing Collections (by Internal ID)

Existing Collections can be referenced by their Internal ID specified in the Collections array:

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "Collections": [
        {
          "InternalId": "coll-100"
        }
      ]
    }
  }
}

Creating New Collections

Editorial collections can be created by specifying the type accordingly:

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "Collections": [
        {
          "InternalId": "coll-100",
          "InternalTitle": "Season 2025 Highlights",
          "DisplayTitle": "Season '25 Highlights",
          "Type": "Editorial"
        }
      ]
    }
  }
}

CategoryBased collections require the CategoryExternalId to be pointing to an existing Category by its External ID. In the following example the existing Category is also added to the Clip so it'll be included in the Collection from the Category.

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "Categories": [
        {
          "ExternalId": "premier-league"
        }
      ],
      "Collections": [
        {
          "InternalId": "coll-100",
          "InternalTitle": "Season 2025 Highlights",
          "DisplayTitle": "Season '25 Highlights",
          "Type": "CategoryBased",
          "CategoryExternalId": "premier-league"
        }
      ]
    }
  }
}

Metadata:

Key	Type	Remarks
Collections	ArrayOf(object)	Collections to associate the clip with.

Collection Object Properties:

Property	Type	Required	Remarks
InternalId	string	Yes*	Unique internal identifier.
InternalTitle	string	No	Internal title for CMS use. Defaults to InternalId.
DisplayTitle	string	No	Display title shown to users. Truncated to max length if needed.
Type	string	Yes	Collection type: "Editorial" or "CategoryBased". Editorial collections associate clips directly while Category Based collections include Clips when added to the category.
CategoryExternalId	string	No	Links collection to a category. Required when creating a category-based collection.

Item Metadata

Add arbitrary key-value metadata to clips:

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "ItemMetadata": {
        "editor": "jdoe",
        "series": "Derby Day",
        "publisher_name": "CNN",
        "production_date": "2025-10-01"
      }
    }
  }
}

Metadata:

Key	Type	Remarks
ItemMetadata	object	Arbitrary key-value pairs stored as clip metadata. Useful for tracking custom fields.

Special Metadata Keys:

• publisher_name: "CNN" - When set to "CNN", uses frame 2 for thumbnail generation to avoid text overlays.

Custom Thumbnails

Static Thumbnail URL

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "ThumbnailUrl": "https://cdn.example.com/images/highlight-001-thumb.jpg"
    }
  }
}

Template-Based Thumbnail

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "ThumbnailTemplate": "thumb-template-01",
      "TemplateMetadata": {
        "style": "bold",
        "watermark": "on"
      }
    }
  }
}

Template with Custom Thumbnail

{
  "workflows": ["add-clip"],
  "mediaUrls": ["https://cdn.example.com/videos/highlight-001.mp4"],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "ThumbnailUrl": "https://cdn.example.com/images/highlight-001-thumb.jpg",
      "ThumbnailTemplate": "thumb-template-01",
      "TemplateMetadata": {
        "overlay": "team-logo"
      }
    }
  }
}

Metadata:

Key	Type	Remarks
ThumbnailUrl	string	Must be an absolute URL. Used as custom thumbnail or as base image for template.
ThumbnailTemplate	string	Thumbnail Template ID to apply. Can be used alone (uses auto-generated thumbnail) or with ThumbnailUrl.
TemplateMetadata	object	Template-specific key-value pairs passed to the template processor.

Thumbnail Processing Behavior:

• ThumbnailUrl only: Sets custom thumbnail directly
• ThumbnailTemplate only: Applies template to auto-generated thumbnail from video
• Both: Applies template to provided custom thumbnail URL

Complete Advanced Example

{
  "workflows": ["add-clip"],
  "mediaUrls": [
    "https://cdn.example.com/videos/highlight-001.mp4"
  ],
  "metadata": {
    "https://cdn.example.com/videos/highlight-001.mp4": {
      "Title": "Derby Day Highlight",
      "DisplayTitle": "Derby Day: 90s Highlight",
      "ExternalId": "ext-clip-001",
      "ItemMetadata": {
        "editor": "jdoe",
        "series": "Derby Day",
        "publisher_name": "CNN"
      },
      "PrimaryActionLinkId": "987ce210-0f79-404b-bd0a-5d6e67b58d3c",
      "SecondaryActionLinkIds": [
        "6df128ea-8aaa-4160-ae6e-382c1bf9727f",
        "d78234c3-16f7-4883-b499-14eeaacd87b8"
      ],
      "CategoryIds": ["premier-league", "featured"],
      "Categories": [
        {
          "ExternalId": "premier-league",
          "DisplayTitle": "Premier League",
          "InternalTitle": "PL",
          "AvailableForNavigation": true,
          "ShowInClips": false,
          "Type": "Other"
        }
      ],
      "Collections": [
        {
          "InternalId": "coll-100",
          "InternalTitle": "Season 2025 Highlights",
          "DisplayTitle": "Season '25 Highlights",
          "Type": "Editorial",
          "CategoryExternalId": "featured"
        }
      ],
      "ThumbnailUrl": "https://cdn.example.com/images/highlight-001-thumb.jpg",
      "ThumbnailTemplate": "thumb-template-01",
      "CreationTime": "2025-10-01T10:00:00Z",
      "TemplateMetadata": {
        "style": "bold",
        "watermark": "on"
      }
    }
  },
  "workflowProcessedWebhookUrl": "https://partner.example.com/webhooks/processed",
  "workflowFailedWebhookUrl": "https://partner.example.com/webhooks/failed"
}

Webhooks

Both workflow completion and failure webhooks are optional but recommended for tracking workflow execution status:

Key	Type	Required	Remarks
workflowProcessedWebhookUrl	string	No	URL called when workflow completes successfully.
workflowFailedWebhookUrl	string	No	URL called when workflow fails.