> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vimeo Integration

> Automatically upload videos to Vimeo with custom privacy settings and folder organization

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

<CardGroup cols={2}>
  <Card title="Auto Upload" icon="vimeo">
    Automatically upload videos to Vimeo
  </Card>

  <Card title="Privacy Controls" icon="shield">
    Configure view, embed, and download settings
  </Card>

  <Card title="Folder Organization" icon="folder">
    Organize videos in Vimeo folders
  </Card>

  <Card title="Content Ratings" icon="check-circle">
    Set appropriate content ratings
  </Card>
</CardGroup>

## Before You Begin

Make sure you have:

* A [Pictory API key](https://app.pictory.ai/api-access)
* Node.js or Python installed on your machine
* A Vimeo account with API access
* Vimeo connection created in Pictory (see setup below)

<CodeGroup>
  ```bash npm theme={null}
  npm install axios
  ```

  ```bash pip theme={null}
  pip install requests
  ```
</CodeGroup>

## 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

<Note>
  You must create a Vimeo connection before using this feature. The connection authorizes Pictory to upload videos to your Vimeo account on your behalf.
</Note>

## Setting Up Vimeo Connection

Before creating videos with Vimeo integration, set up your connection:

### Step 1: Create Vimeo Connection

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  create_connection = requests.post(
      f'{API_BASE_URL}/v1/vimeo/connections',
      json={
          'name': 'My Vimeo Account',
          'accessToken': 'YOUR_VIMEO_ACCESS_TOKEN'
      },
      headers={
          'Content-Type': 'application/json',
          'Authorization': API_KEY
      }
  )

  connection_id = create_connection.json()['id']
  print(f"Connection ID: {connection_id}")
  ```
</CodeGroup>

### Step 2: List Your Connections

<CodeGroup>
  ```javascript Node.js theme={null}
  const connections = await axios.get(
    `${API_BASE_URL}/v1/vimeo/connections`,
    { headers: { Authorization: API_KEY } }
  );

  console.log("Your Vimeo connections:", connections.data);
  ```

  ```python Python theme={null}
  connections = requests.get(
      f'{API_BASE_URL}/v1/vimeo/connections',
      headers={'Authorization': API_KEY}
  )

  print("Your Vimeo connections:", connections.json())
  ```
</CodeGroup>

See [Create Vimeo Connection](/api-reference/vimeo-integration/create-vimeo-connection) for detailed setup instructions.

## Complete Example

<CodeGroup>
  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  import requests
  import time
  import json

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

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

  def create_video_with_vimeo():
      try:
          print("Creating video with Vimeo upload...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  '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
              }
          )
          response.raise_for_status()

          job_id = response.json()['data']['jobId']
          print("✓ Video creation started!")
          print(f"Job ID: {job_id}")

          # Monitor progress
          print("\nMonitoring video creation and Vimeo upload...")
          job_completed = False
          job_result = None

          while not job_completed:
              status_response = requests.get(
                  f'{API_BASE_URL}/v1/jobs/{job_id}',
                  headers={'Authorization': API_KEY}
              )
              status_response.raise_for_status()

              status = status_response.json()['data']['status']
              print(f"Status: {status}")

              if status == 'completed':
                  job_completed = True
                  job_result = status_response.json()
                  print("\n✓ Video created and uploaded to Vimeo!")
                  print(f"Pictory URL: {job_result['data']['videoURL']}")
                  if job_result['data'].get('destinations'):
                      print(f"Vimeo URL: {job_result['data']['destinations'][0].get('videoLink')}")
              elif status == 'failed':
                  raise Exception(f"Video creation failed: {status_response.json()}")

              time.sleep(5)

          return job_result

      except requests.exceptions.RequestException as error:
          print(f"Error: {error}")
          if hasattr(error, 'response') and error.response is not None:
              print(f"Response: {error.response.text}")
          raise

  if __name__ == '__main__':
      create_video_with_vimeo()
  ```
</CodeGroup>

## 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 |

<Tip>
  You can specify multiple content ratings. For example: `["safe", "advertisement"]` for a family-friendly commercial.
</Tip>

## Common Use Cases

### Public Marketing Video

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Choose Appropriate Privacy Settings">
    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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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 does not stop others
    * **Track URLs:** Response includes URLs for all destinations
    * **Verify All:** Check each destination uploaded successfully
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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 are using the ID, not the connection name
  </Accordion>

  <Accordion title="Video created but not uploaded to Vimeo">
    **Problem:** Video is created successfully but does not 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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Folder URI not working">
    **Problem:** Video does not 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/`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Multiple destinations failing">
    **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) is not exceeded
  </Accordion>
</AccordionGroup>

## Next Steps

Explore more advanced features and integrations:

<CardGroup cols={2}>
  <Card title="AWS S3 Integration" icon="aws" href="/api-reference/aws-integration/aws-private-connection">
    Upload videos to AWS S3 storage
  </Card>

  <Card title="Background Music" icon="music" href="/guides/advanced-features/background-music">
    Add music to your videos
  </Card>

  <Card title="Intro/Outro Videos" icon="clapperboard" href="/guides/advanced-features/intro-outro">
    Add branded intro and outro sequences
  </Card>

  <Card title="Save Project" icon="floppy-disk" href="/guides/advanced-features/save-project">
    Save video projects for later editing
  </Card>
</CardGroup>

## API Reference

For complete technical details on Vimeo integration, see:

* [Create Vimeo Connection](/api-reference/vimeo-integration/create-vimeo-connection) - Set up new Vimeo connections
* [Get Vimeo Connections](/api-reference/vimeo-integration/get-vimeo-connections) - List all your Vimeo connections
* [Get Vimeo Connection by ID](/api-reference/vimeo-integration/get-vimeo-connection-by-id) - Get details of a specific connection
* [Update Vimeo Connection](/api-reference/vimeo-integration/update-vimeo-connection) - Modify existing connections
* [Delete Vimeo Connection](/api-reference/vimeo-integration/delete-vimeo-connection) - Remove Vimeo connections
* [Render Storyboard Video](/api-reference/videos/render-storyboard-video) - Full video creation API specification
* [Get Job Status](/api-reference/jobs/get-video-render-job-by-id) - Monitor job status and progress