Skip to main content
This guide shows you how to create videos with Pictory and automatically upload them to Vimeo with custom privacy settings, content ratings, and folder organization. Perfect for streamlining your video workflow.

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)
npm install axios

How Vimeo Integration Works

When you create a video with Vimeo destination:
  1. Video Creation - Your video is created by Pictory API
  2. Connection Verification - Vimeo connection is validated
  3. Privacy Setup - Your specified privacy settings are configured
  4. Folder Assignment - Video is placed in designated Vimeo folder (if specified)
  5. Upload Process - Video is automatically uploaded to Vimeo
  6. 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

const createConnection = await axios.post(
  `${API_BASE_URL}/v1/vimeo/connections`,
  {
    name: "My Vimeo Account",
    accessToken: "YOUR_VIMEO_ACCESS_TOKEN"
  },
  {
    headers: {
      "Content-Type": "application/json",
      Authorization: API_KEY
    }
  }
);

const connectionId = createConnection.data.id;
console.log("Connection ID:", connectionId);

Step 2: List Your Connections

const connections = await axios.get(
  `${API_BASE_URL}/v1/vimeo/connections`,
  { headers: { Authorization: API_KEY } }
);

console.log("Your Vimeo connections:", connections.data);
See Create Vimeo Connection for detailed setup instructions.

Complete Example

import axios from "axios";

const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const API_KEY = "YOUR_API_KEY";

const SAMPLE_TEXT = "AI is poised to significantly impact educators and course creators on social media.";

async function createVideoWithVimeo() {
  try {
    console.log("Creating video with Vimeo upload...");

    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "text_to_video_vimeo",
        vimeoConnectionId: "{YOUR_VIMEO_CONNECTION_ID}",  // Your Vimeo connection ID

        // Vimeo destination configuration
        destinations: [
          {
            type: "vimeo",
            folder_uri: "/videos/123456",       // Optional: Vimeo folder URI
            content_rating: ["safe"],           // Content rating

            // Privacy settings
            privacy: {
              view: "unlisted",                 // Who can view the video
              embed: "public",                  // Who can embed the video
              comments: "anybody",              // Who can comment
              download: false,                  // Allow downloads
              add: false,                       // Allow adding to albums
            },
          },
        ],

        // Scene configuration
        scenes: [
          {
            story: SAMPLE_TEXT,
            createSceneOnNewLine: false,
            createSceneOnEndOfSentence: false,
          },
        ],
      },
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: API_KEY,
        },
      }
    );

    const jobId = response.data.data.jobId;
    console.log("✓ Video creation started!");
    console.log("Job ID:", jobId);

    // Monitor progress
    console.log("\nMonitoring video creation and Vimeo upload...");
    let jobCompleted = false;
    let jobResult = null;

    while (!jobCompleted) {
      const statusResponse = await axios.get(
        `${API_BASE_URL}/v1/jobs/${jobId}`,
        {
          headers: { Authorization: API_KEY },
        }
      );

      const status = statusResponse.data.data.status;
      console.log("Status:", status);

      if (status === "completed") {
        jobCompleted = true;
        jobResult = statusResponse.data;
        console.log("\n✓ Video created and uploaded to Vimeo!");
        console.log("Pictory URL:", jobResult.data.videoURL);
        console.log("Vimeo URL:", jobResult.data.destinations?.[0]?.videoLink);
      } else if (status === "failed") {
        throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
      }

      await new Promise(resolve => setTimeout(resolve, 5000));
    }

    return jobResult;
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
    throw error;
  }
}

createVideoWithVimeo();

Understanding the Parameters

Main Request Parameters

ParameterTypeRequiredDescription
videoNamestringYesA descriptive name for your video project
vimeoConnectionIdstringYesYour Vimeo connection ID from Pictory
destinationsarrayYesArray of destination configurations (can include multiple)
scenesarrayYesVideo scene configuration

Destination Configuration

ParameterTypeRequiredDescription
typestringYesMust be "vimeo" for Vimeo uploads
folder_uristringNoVimeo folder URI (e.g., /videos/123456)
content_ratingarrayNoContent rating tags (see options below)
privacyobjectNoPrivacy and permission settings

Privacy Settings

Control who can view, embed, and interact with your video:
SettingOptionsDescription
viewanybody, contacts, disable, nobody, password, unlisted, usersWho can view the video
embedprivate, public, whitelistWho can embed the video on other sites
commentsanybody, contacts, nobodyWho can leave comments
downloadtrue, falseAllow video downloads
addtrue, falseAllow adding video to albums/channels

View Privacy Options Explained

OptionDescriptionBest Used For
anybodyPublic - anyone can viewPublic content, marketing videos
unlistedAnyone with the link can view (not listed publicly)Shareable but not discoverable content
passwordRequires password to viewConfidential presentations, client reviews
contactsOnly your Vimeo contacts can viewTeam-only content
usersOnly logged-in Vimeo users can viewRestricted professional content
nobodyPrivate - only you can viewPersonal archive, work in progress
disableVideo is disabledTemporarily unavailable

Embed Privacy Options

OptionDescription
publicAnyone can embed the video on their website
privateVideo cannot be embedded anywhere
whitelistOnly whitelisted domains can embed

Content Rating Options

Tag your video with appropriate content ratings:
RatingDescription
safeSafe for general audiences
unratedNo rating specified
violenceContains violent content
drugsContains drug-related content
languageContains strong language
nudityContains nudity or sexual content
advertisementCommercial or advertising content
You can specify multiple content ratings. For example: ["safe", "advertisement"] for a family-friendly commercial.

Common Use Cases

Public Marketing Video

{
  vimeoConnectionId: "conn_123abc",
  destinations: [{
    type: "vimeo",
    content_rating: ["safe", "advertisement"],
    privacy: {
      view: "anybody",
      embed: "public",
      comments: "anybody",
      download: false
    }
  }]
}
Result: Video is public, embeddable, and allows comments.

Unlisted Shareable Video

{
  vimeoConnectionId: "conn_123abc",
  destinations: [{
    type: "vimeo",
    content_rating: ["safe"],
    privacy: {
      view: "unlisted",
      embed: "public",
      comments: "contacts",
      download: false
    }
  }]
}
Result: Video accessible via link, embeddable, but not listed publicly.

Private Client Review

{
  vimeoConnectionId: "conn_123abc",
  destinations: [{
    type: "vimeo",
    folder_uri: "/videos/client_reviews",
    content_rating: ["unrated"],
    privacy: {
      view: "password",
      embed: "private",
      comments: "contacts",
      download: true
    }
  }]
}
Result: Password-protected video for client review with download option.

Team-Only Training Video

{
  vimeoConnectionId: "conn_123abc",
  destinations: [{
    type: "vimeo",
    folder_uri: "/videos/training",
    content_rating: ["safe"],
    privacy: {
      view: "contacts",
      embed: "private",
      comments: "contacts",
      download: false
    }
  }]
}
Result: Private video only viewable by Vimeo contacts.

Best Practices

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
Select privacy settings based on your use case:
  • Public Content: Use anybody view + public embed
  • Shareable but Private: Use unlisted view
  • Team Only: Use contacts or users view
  • Client Reviews: Use password view with download enabled
  • Work in Progress: Use nobody view until ready
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
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
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

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
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
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
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/
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
Problem: Video created but all destination uploads fail.Solution:
  • Check destinations array is properly formatted
  • Ensure each destination has required type parameter
  • 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:

API Reference

For complete technical details on Vimeo integration, see: