Add Media

Adds media into the Media Library. Use this for storing raw assets (videos/images) for later use in clips, stories, or other workflows. Optionally targets a specific media library by title.

• Workflow ID: add-media

Example Request

{
  "workflows": ["add-media"],
  "mediaUrls": [
    "https://cdn.example.com/media/video-001.mp4",
    "https://cdn.example.com/media/video-002.mp4"
  ],
  "metadata": {
    "MediaLibraryTitle": "Primary Media Library",

    "https://cdn.example.com/media/video-001.mp4": {
      "Title": "Example Media 001",
      "Width": 1080,
      "Height": 1920,
      "ExternalId": "ext-media-001",
      "ExternalCallback": "https://partner.example.com/callback/media-001",
      "MediaMetadata": {
        "source": "partner-feed",
        "tag": "feature"
      }
    },
    "https://cdn.example.com/media/video-002.mp4": {
      "Title": "Example Media 002",
      "Width": 720,
      "Height": 1280,
      "ExternalId": "ext-media-002",
      "MediaMetadata": {
        "source": "partner-feed",
        "tag": "alt"
      }
    }
  },
  "workflowProcessedWebhookUrl": "https://partner.example.com/webhooks/processed",
  "workflowFailedWebhookUrl": "https://partner.example.com/webhooks/failed"
}

Metadata

Key	Type	Required	Remarks
MediaLibraryTitle	string	No	Root-level. Name of media library to place items in.
Title	string	Yes	Per-media. Title for the media item.
Width	integer	No	Per-media. Pixel width (if known).
Height	integer	No	Per-media. Pixel height (if known).
ExternalId	string	No	Per-media. External identifier you control for idempotency and lookup.
ExternalCallback	string	No	Per-media. Callback token you can later correlate in internal logs.
MediaMetadata	object	No	Per-media. Arbitrary key/value pairs stored with the media.

cURL Example

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-media"],
  "mediaUrls": [
    "https://cdn.example.com/media/video-001.mp4"
  ],
  "metadata": {
    "MediaLibraryTitle": "Primary Media Library",
    "https://cdn.example.com/media/video-001.mp4": {
      "Title": "Example Media 001",
      "Width": 1080,
      "Height": 1920,
      "ExternalId": "ext-media-001",
      "MediaMetadata": {"source": "partner-feed"}
    }
  }
}
JSON