What You’ll Learn
Auto Upload
Automatically upload videos to Vimeo
Privacy Controls
Configure view, embed, and download settings
Folder Organization
Organize videos in Vimeo folders
Content Ratings
Set appropriate content ratings
Before You Begin
Make sure you have:- A Pictory API key (get one here)
- Node.js or Python installed on your machine
- A Vimeo account with API access
- Vimeo connection created in Pictory (see setup below)
How Vimeo Integration Works
When you create a video with Vimeo destination:- Video Creation - Your video is created by Pictory API
- Connection Verification - Vimeo connection is validated
- Privacy Setup - Your specified privacy settings are configured
- Folder Assignment - Video is placed in designated Vimeo folder (if specified)
- Upload Process - Video is automatically uploaded to Vimeo
- Response Delivery - Both Pictory and Vimeo URLs are returned
You must create a Vimeo connection before using this feature. The connection authorizes Pictory to upload videos to your Vimeo account on your behalf.
Setting Up Vimeo Connection
Before creating videos with Vimeo integration, set up your connection:Step 1: Create Vimeo Connection
Step 2: List Your Connections
Complete Example
Understanding the Parameters
Main Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
videoName | string | Yes | A descriptive name for your video project |
vimeoConnectionId | string | Yes | Your Vimeo connection ID from Pictory |
destinations | array | Yes | Array of destination configurations (can include multiple) |
scenes | array | Yes | Video scene configuration |
Destination Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Must be "vimeo" for Vimeo uploads |
folder_uri | string | No | Vimeo folder URI (e.g., /videos/123456) |
content_rating | array | No | Content rating tags (see options below) |
privacy | object | No | Privacy and permission settings |
Privacy Settings
Control who can view, embed, and interact with your video:| Setting | Options | Description |
|---|---|---|
view | anybody, contacts, disable, nobody, password, unlisted, users | Who can view the video |
embed | private, public, whitelist | Who can embed the video on other sites |
comments | anybody, contacts, nobody | Who can leave comments |
download | true, false | Allow video downloads |
add | true, false | Allow adding video to albums/channels |
View Privacy Options Explained
| Option | Description | Best Used For |
|---|---|---|
anybody | Public - anyone can view | Public content, marketing videos |
unlisted | Anyone with the link can view (not listed publicly) | Shareable but not discoverable content |
password | Requires password to view | Confidential presentations, client reviews |
contacts | Only your Vimeo contacts can view | Team-only content |
users | Only logged-in Vimeo users can view | Restricted professional content |
nobody | Private - only you can view | Personal archive, work in progress |
disable | Video is disabled | Temporarily unavailable |
Embed Privacy Options
| Option | Description |
|---|---|
public | Anyone can embed the video on their website |
private | Video cannot be embedded anywhere |
whitelist | Only whitelisted domains can embed |
Content Rating Options
Tag your video with appropriate content ratings:| Rating | Description |
|---|---|
safe | Safe for general audiences |
unrated | No rating specified |
violence | Contains violent content |
drugs | Contains drug-related content |
language | Contains strong language |
nudity | Contains nudity or sexual content |
advertisement | Commercial or advertising content |
Common Use Cases
Public Marketing Video
Unlisted Shareable Video
Private Client Review
Team-Only Training Video
Best Practices
Set Up Connection Securely
Set Up Connection Securely
Protect your Vimeo access credentials:
- Secure Storage: Store Vimeo access tokens securely, not in code
- Environment Variables: Use environment variables for sensitive data
- Connection Names: Use descriptive names for multiple connections
- Regular Rotation: Periodically rotate access tokens
- Test First: Verify connection works before production use
Choose Appropriate Privacy Settings
Choose Appropriate Privacy Settings
Select privacy settings based on your use case:
- Public Content: Use
anybodyview +publicembed - Shareable but Private: Use
unlistedview - Team Only: Use
contactsorusersview - Client Reviews: Use
passwordview with download enabled - Work in Progress: Use
nobodyview until ready
Organize with Folders
Organize with Folders
Use Vimeo folders for better organization:
- Get Folder URI: Navigate to folder in Vimeo, check URL for URI
- Consistent Structure: Create logical folder hierarchy
- By Project: Organize by client, campaign, or project
- By Type: Separate by content type (marketing, training, etc.)
- Pre-Create Folders: Set up folders in Vimeo before API use
Set Accurate Content Ratings
Set Accurate Content Ratings
Tag videos appropriately:
- Be Honest: Accurate ratings help with content discovery
- Multiple Tags: Use multiple ratings when applicable
- Safe Tag: Use for family-friendly content
- Advertisement: Always tag commercial content
- Review Guidelines: Follow Vimeo’s community guidelines
Handle Multiple Destinations
Handle Multiple Destinations
You can upload to multiple platforms:
- Multiple Destinations: Specify up to 5 destinations per video
- Different Settings: Each destination can have unique settings
- Error Handling: One destination failure doesn’t stop others
- Track URLs: Response includes URLs for all destinations
- Verify All: Check each destination uploaded successfully
Troubleshooting
Error: Invalid Vimeo connection
Error: Invalid Vimeo connection
Problem: API returns error about invalid or missing connection.Solution:
- Verify connection ID is correct
- Use Get Vimeo Connections API to list valid connections
- Ensure connection hasn’t been deleted
- Check Vimeo access token is still valid
- Re-create connection if necessary
- Ensure you’re using the ID, not the connection name
Video created but not uploaded to Vimeo
Video created but not uploaded to Vimeo
Problem: Video is created successfully but doesn’t appear on Vimeo.Solution:
- Check job response for destination upload status
- Verify Vimeo connection has upload permissions
- Check Vimeo account storage quota
- Review Vimeo API rate limits
- Verify folder URI exists in your Vimeo account
- Check destinations array in response for error messages
Privacy settings not applied
Privacy settings not applied
Problem: Video uploads but privacy settings are different than specified.Solution:
- Verify privacy object syntax is correct
- Check Vimeo account permissions (some settings require paid plans)
- Ensure password is provided if view is set to “password”
- Confirm whitelist domains if embed is “whitelist”
- Review Vimeo’s default settings for your account
Folder URI not working
Folder URI not working
Problem: Video doesn’t appear in specified Vimeo folder.Solution:
- Get folder URI from Vimeo folder URL (e.g.,
/videos/123456) - Ensure folder exists in your Vimeo account before uploading
- Check folder permissions (you must be owner or have access)
- Try omitting folder_uri to upload to account root first
- Verify folder URI format starts with
/videos/
Upload takes very long
Upload takes very long
Problem: Video processing completes but Vimeo upload is slow.Solution:
- Vimeo upload time depends on video size and length
- Large videos (over 1GB) may take 15-30 minutes additional time
- Check your internet connection speed
- Vimeo may be processing the video on their end
- Monitor job status - it will show “completed” when fully done
- Consider reducing video resolution/quality if uploads consistently timeout
Multiple destinations failing
Multiple destinations failing
Problem: Video created but all destination uploads fail.Solution:
- Check destinations array is properly formatted
- Ensure each destination has required
typeparameter - Verify connection IDs for all destination types
- Test with single destination first
- Check API response for specific destination errors
- Ensure destination limit (5 max) isn’t exceeded
Next Steps
Explore more advanced features and integrations:AWS S3 Integration
Upload videos to AWS S3 storage
Background Music
Add music to your videos
Intro/Outro Videos
Add branded intro and outro sequences
Save Project
Save video projects for later editing
API Reference
For complete technical details on Vimeo integration, see:- Create Vimeo Connection - Set up new Vimeo connections
- Get Vimeo Connections - List all your Vimeo connections
- Get Vimeo Connection by ID - Get details of a specific connection
- Update Vimeo Connection - Modify existing connections
- Delete Vimeo Connection - Remove Vimeo connections
- Render Storyboard Video - Full video creation API specification
- Get Job Status - Monitor job status and progress
