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

# AI Story Generation with Story CoPilot

> Generate video scripts automatically using AI-powered Story CoPilot in the Pictory API

This guide shows you how to use the Story CoPilot feature to automatically generate video scripts from a simple prompt. Instead of writing your own story content, let AI create engaging, platform-optimized scripts tailored to your video type and tone preferences.

## What You'll Learn

<CardGroup cols={2}>
  <Card title="AI Script Generation" icon="wand-magic-sparkles">
    Generate video scripts from simple prompts
  </Card>

  <Card title="Video Type Optimization" icon="video">
    Create content optimized for different video types
  </Card>

  <Card title="Platform Targeting" icon="bullseye">
    Tailor scripts for specific social platforms
  </Card>

  <Card title="Tone Control" icon="sliders">
    Adjust the voice and style of generated content
  </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 clear idea of your video topic
* Understanding of your target audience and platform

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

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

## How Story CoPilot Works

When you use Story CoPilot to generate a video:

1. **Prompt Submission** - You provide a topic or description for your video
2. **AI Processing** - The CoPilot AI analyzes your prompt along with video type, platform, and tone settings
3. **Script Generation** - AI generates an optimized script tailored to your specifications
4. **Scene Creation** - The generated script is split into scenes based on your settings
5. **Visual Selection** - AI selects appropriate stock visuals for each scene
6. **Video Rendering** - Final video is assembled with voiceover, visuals, and captions

<Note>
  Story CoPilot generates content based on your prompt and settings. The AI considers video type, target platform, and tone to create contextually appropriate scripts that engage your intended audience.
</Note>

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

  async function createVideoWithStoryCoPilot() {
    try {
      console.log("Creating video with AI-generated script...");

      const response = await axios.post(
        `${API_BASE_URL}/v2/video/storyboard/render`,
        {
          videoName: "ai_generated_video",

          // Voice-over configuration
          voiceOver: {
            enabled: true,
            aiVoices: [
              {
                speaker: "Brian",
                speed: 100,
                amplificationLevel: 0,
              },
            ],
          },

          // Scene with Story CoPilot
          scenes: [
            {
              // Story CoPilot configuration
              storyCoPilot: {
                prompt: "How artificial intelligence is transforming video creation and making professional content accessible to everyone",
                videoType: "Explainer",           // Type of video
                duration: 60,                      // Target duration in seconds
                platform: "YouTube",               // Target platform
                tone: "informative",               // Content tone
              },
              createSceneOnEndOfSentence: true,
            },
          ],
        },
        {
          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...");
      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 with AI-generated script is ready!");
          console.log("Video URL:", jobResult.data.videoURL);
        } 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;
    }
  }

  createVideoWithStoryCoPilot();
  ```

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

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

  def create_video_with_story_copilot():
      try:
          print("Creating video with AI-generated script...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  'videoName': 'ai_generated_video',

                  # Voice-over configuration
                  'voiceOver': {
                      'enabled': True,
                      'aiVoices': [
                          {
                              'speaker': 'Brian',
                              'speed': 100,
                              'amplificationLevel': 0
                          }
                      ]
                  },

                  # Scene with Story CoPilot
                  'scenes': [
                      {
                          # Story CoPilot configuration
                          'storyCoPilot': {
                              'prompt': 'How artificial intelligence is transforming video creation and making professional content accessible to everyone',
                              'videoType': 'Explainer',           # Type of video
                              'duration': 180,                      # Target duration in seconds
                              'platform': 'YouTube',               # Target platform
                              'tone': 'informative'                # Content tone
                          },
                          'createSceneOnEndOfSentence': True
                      }
                  ]
              },
              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...")
          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 with AI-generated script is ready!")
                  print(f"Video URL: {job_result['data']['videoURL']}")
              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_story_copilot()
  ```
</CodeGroup>

## Understanding the Parameters

### Story CoPilot Configuration

| Parameter                | Type   | Required | Description                                                             |
| ------------------------ | ------ | -------- | ----------------------------------------------------------------------- |
| `storyCoPilot.prompt`    | string | Yes      | The topic or description for AI to generate content (1-5000 characters) |
| `storyCoPilot.videoType` | string | No       | Type of video to create (default: "Explainer")                          |
| `storyCoPilot.duration`  | number | No       | Target video duration in seconds (1-600)                                |
| `storyCoPilot.platform`  | string | No       | Target social media platform for optimization                           |
| `storyCoPilot.tone`      | string | No       | Tone and style of the generated content                                 |

### Video Types

| Value                    | Description                                        | Best Used For                                            |
| ------------------------ | -------------------------------------------------- | -------------------------------------------------------- |
| `Explainer`              | Educational content that explains concepts clearly | How-to videos, concept explanations, educational content |
| `Marketing`              | Promotional content designed to engage and convert | Product promotions, brand awareness, advertising         |
| `Internal Communication` | Professional content for internal teams            | Company updates, training videos, team announcements     |
| `Tutorial`               | Step-by-step instructional content                 | Software tutorials, DIY guides, learning materials       |
| `Product`                | Product-focused content highlighting features      | Product demos, feature showcases, launch videos          |

### Target Platforms

| Value       | Optimization                           | Typical Duration |
| ----------- | -------------------------------------- | ---------------- |
| `YouTube`   | Longer-form, detailed content          | 2-10 minutes     |
| `TikTok`    | Short, punchy, trend-aware content     | 15-60 seconds    |
| `Instagram` | Visual-first, engaging content         | 30-90 seconds    |
| `Facebook`  | Shareable, social-friendly content     | 1-3 minutes      |
| `LinkedIn`  | Professional, business-focused content | 1-3 minutes      |
| `Twitter`   | Concise, attention-grabbing content    | 15-45 seconds    |

### Content Tones

| Value            | Style                        | Best Used For                      |
| ---------------- | ---------------------------- | ---------------------------------- |
| `professional`   | Formal, business-appropriate | Corporate content, B2B videos      |
| `casual`         | Relaxed, everyday language   | Social media, lifestyle content    |
| `friendly`       | Warm, approachable           | Customer-facing content, tutorials |
| `informative`    | Clear, fact-focused          | Educational content, explainers    |
| `persuasive`     | Compelling, action-oriented  | Marketing, sales videos            |
| `exciting`       | Energetic, enthusiastic      | Product launches, announcements    |
| `educational`    | Teaching-focused, structured | Training, learning materials       |
| `humorous`       | Light-hearted, entertaining  | Social media, brand personality    |
| `serious`        | Grave, important             | Announcements, compliance content  |
| `conversational` | Natural, dialogue-like       | Vlogs, personal content            |

<Warning>
  **Important Considerations**

  * Story CoPilot requires a valid prompt (1-5000 characters)
  * Cannot be used together with `story`, `blogUrl`, `pptUrl`, `audioUrl`, or `videoUrl` in the same scene
  * The generated content quality depends on the clarity and specificity of your prompt
  * Duration is a target guide - actual length may vary based on generated content
</Warning>

## Common Use Cases

### YouTube Explainer Video

```javascript theme={null}
{
  scenes: [{
    storyCoPilot: {
      prompt: "The benefits of renewable energy sources and how they're changing the future of power generation",
      videoType: "Explainer",
      duration: 180,
      platform: "YouTube",
      tone: "informative"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

### TikTok Marketing Content

```javascript theme={null}
{
  scenes: [{
    storyCoPilot: {
      prompt: "Why our new fitness app helps you achieve your workout goals faster than any other app",
      videoType: "Marketing",
      duration: 30,
      platform: "TikTok",
      tone: "exciting"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

### LinkedIn Professional Update

```javascript theme={null}
{
  scenes: [{
    storyCoPilot: {
      prompt: "How remote work is reshaping corporate culture and what leaders need to know",
      videoType: "Internal Communication",
      duration: 90,
      platform: "LinkedIn",
      tone: "professional"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

### Instagram Product Showcase

```javascript theme={null}
{
  scenes: [{
    storyCoPilot: {
      prompt: "Introducing our new eco-friendly water bottle with temperature control technology",
      videoType: "Product",
      duration: 45,
      platform: "Instagram",
      tone: "friendly"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

### Tutorial Video

```javascript theme={null}
{
  scenes: [{
    storyCoPilot: {
      prompt: "Step-by-step guide to setting up a home office for maximum productivity",
      videoType: "Tutorial",
      duration: 120,
      platform: "YouTube",
      tone: "educational"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

## Combining with Other Features

### With Custom Voice Settings

```javascript theme={null}
{
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Emma",
      speed: 95,
      amplificationLevel: 0
    }]
  },
  scenes: [{
    storyCoPilot: {
      prompt: "Your topic here...",
      videoType: "Explainer",
      tone: "friendly"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

### With Background Music

```javascript theme={null}
{
  backgroundMusic: {
    enabled: true,
    autoMusic: true,
    volume: 0.3
  },
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Brian",
      speed: 100
    }]
  },
  scenes: [{
    storyCoPilot: {
      prompt: "Your topic here...",
      videoType: "Marketing",
      tone: "exciting"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

### With Brand Settings

```javascript theme={null}
{
  brandName: "Your Brand Name",
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Matthew",
      speed: 100
    }]
  },
  scenes: [{
    storyCoPilot: {
      prompt: "Your topic here...",
      videoType: "Marketing",
      platform: "LinkedIn",
      tone: "professional"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

### With Subtitle Styling

```javascript theme={null}
{
  subtitleStyleName: "Corporate Blue",
  voiceOver: {
    enabled: true,
    aiVoices: [{
      speaker: "Joanna",
      speed: 100
    }]
  },
  scenes: [{
    storyCoPilot: {
      prompt: "Your topic here...",
      videoType: "Internal Communication",
      tone: "professional"
    },
    createSceneOnEndOfSentence: true
  }]
}
```

## Writing Effective Prompts

<AccordionGroup>
  <Accordion title="Be Specific and Detailed">
    More detail in your prompt leads to better results:

    **Less Effective:**

    ```
    "Talk about AI"
    ```

    **More Effective:**

    ```
    "Explain how artificial intelligence is being used in healthcare to improve patient diagnosis accuracy and reduce waiting times in emergency rooms"
    ```
  </Accordion>

  <Accordion title="Include Key Points">
    Mention specific points you want covered:

    **Example:**

    ```
    "Create a video about electric vehicles covering: environmental benefits, cost savings on fuel, available tax incentives, and the growing charging infrastructure"
    ```
  </Accordion>

  <Accordion title="Specify Your Audience">
    Help the AI understand who you are speaking to:

    **Example:**

    ```
    "Explain blockchain technology for small business owners who have no technical background but want to understand how it could benefit their operations"
    ```
  </Accordion>

  <Accordion title="Include Call-to-Action Intent">
    If you want viewers to take action, mention it:

    **Example:**

    ```
    "Promote our new project management software, highlighting the time-saving features and encouraging viewers to sign up for a free trial"
    ```
  </Accordion>

  <Accordion title="Set the Context">
    Provide background information when helpful:

    **Example:**

    ```
    "Given the recent rise in remote work, explain how team collaboration tools have evolved and what features modern teams should look for in 2024"
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Match Video Type to Content">
    Choose the video type that best fits your goal:

    * **Explainer:** When educating or informing
    * **Marketing:** When promoting or selling
    * **Tutorial:** When teaching step-by-step processes
    * **Product:** When showcasing features and benefits
    * **Internal Communication:** For company/team content
  </Accordion>

  <Accordion title="Optimize for Platform">
    Set the platform to get content optimized for that audience:

    * **TikTok:** Shorter, trend-aware, attention-grabbing
    * **YouTube:** More detailed, structured, SEO-friendly
    * **LinkedIn:** Professional, business-focused language
    * **Instagram:** Visual-first, engaging hooks
  </Accordion>

  <Accordion title="Use Appropriate Tone">
    Match tone to your brand and audience:

    * **B2B Content:** Professional, informative
    * **Consumer Marketing:** Friendly, exciting, persuasive
    * **Educational:** Informative, educational
    * **Social Media:** Casual, conversational, humorous
  </Accordion>

  <Accordion title="Set Realistic Durations">
    Guide the AI with appropriate target lengths:

    * Short social content: 15-60 seconds
    * Standard videos: 60-180 seconds
    * Detailed content: 180-600 seconds
    * The AI will adjust content density accordingly
  </Accordion>

  <Accordion title="Review and Iterate">
    Story CoPilot is a starting point:

    * Review the generated content
    * Create variations with different prompts
    * Adjust tone or platform settings for different results
    * Use the best output as your final video
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Generated content is too generic">
    **Problem:** The AI-generated script lacks specificity.

    **Solution:**

    * Make your prompt more detailed and specific
    * Include key points you want covered
    * Mention your target audience
    * Add context or background information
    * Specify industry or domain terminology
  </Accordion>

  <Accordion title="Content Does Not Match Expected Tone">
    **Problem:** The generated script does not feel right for your brand.

    **Solution:**

    * Try a different tone setting
    * Adjust the videoType to better match your needs
    * Include tone guidance in your prompt
    * Combine tones (e.g., "professional yet friendly")
    * Test multiple tone options to find the best fit
  </Accordion>

  <Accordion title="Video is too long or too short">
    **Problem:** Generated content does not match target duration.

    **Solution:**

    * Adjust the `duration` parameter
    * Note that duration is a target, not exact
    * Longer prompts may generate longer content
    * Shorter prompts may generate shorter content
    * Platform setting also influences content length
  </Accordion>

  <Accordion title="Error: Cannot use storyCoPilot with story">
    **Problem:** API returns error about conflicting parameters.

    **Solution:**

    * Remove the `story` parameter when using `storyCoPilot`
    * Only one content source allowed per scene
    * Choose either: storyCoPilot, story, blogUrl, pptUrl, audioUrl, or videoUrl
    * Each scene can only have one content source
  </Accordion>

  <Accordion title="Content seems off-topic">
    **Problem:** Generated script does not address your intended topic.

    **Solution:**

    * Rephrase your prompt more clearly
    * Start with the main topic explicitly stated
    * Remove ambiguous wording
    * Be direct about what you want covered
    * Check for typos or unclear references
  </Accordion>
</AccordionGroup>

## Next Steps

Enhance your AI-generated videos with these features:

<CardGroup cols={2}>
  <Card title="AI Voice-Over" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Add professional narration to your videos
  </Card>

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

  <Card title="Brand Settings" icon="palette" href="/guides/branding-customization/brand-settings">
    Apply consistent branding across videos
  </Card>

  <Card title="Smart Layouts" icon="table-layout" href="/guides/smart-layouts-and-subtitles/smart-layouts">
    Use pre-designed layouts for professional presentation
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

* [Render Storyboard Video](/api-reference/videos/render-storyboard-video) - Full API specification
* [Get Job Status](/api-reference/jobs/get-video-render-job-by-id) - Monitor job status and progress
* [Get Voiceover Tracks](/api-reference/voiceovers/get-voiceover-tracks) - List available AI voices