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

# Basic Text to Video

> Create a simple video from text using the Pictory API with automatic visual selection

This guide shows you how to turn written text into an engaging video with automatically selected visuals. Perfect for creating social media content, educational videos, or marketing materials from your written content.

## What You'll Learn

<CardGroup cols={2}>
  <Card title="Text to Video" icon="text">
    Transform written content into engaging videos
  </Card>

  <Card title="Auto Visuals" icon="images">
    AI selects visuals based on your text content
  </Card>

  <Card title="Scene Control" icon="layer-group">
    Control how text is split into scenes
  </Card>

  <Card title="Job Monitoring" icon="clock">
    Track video creation progress in real-time
  </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
* The required packages installed

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

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

## Step-by-Step Guide

### Step 1: Set Up Your Request

First, prepare your API credentials and the text you want to convert:

<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"; // Replace with your actual API key

  // Your text content - this will be converted into video
  const SAMPLE_TEXT =
    "AI is transforming how we create content. By automating video production, " +
    "creators can focus on strategy while AI handles the technical work. " +
    "This means faster turnaround times and consistent quality across all videos.";
  ```

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

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'  # Replace with your actual API key

  # Your text content - this will be converted into video
  SAMPLE_TEXT = (
      "AI is transforming how we create content. By automating video production, "
      "creators can focus on strategy while AI handles the technical work. "
      "This means faster turnaround times and consistent quality across all videos."
  )
  ```
</CodeGroup>

### Step 2: Create the Video

Send your text to the API to start the video creation process:

<CodeGroup>
  ```javascript Node.js theme={null}
  async function createTextToVideo() {
    try {
      console.log("Creating video from text...");

      const response = await axios.post(
        `${API_BASE_URL}/v2/video/storyboard/render`,
        {
          videoName: "my_first_text_video",
          scenes: [
            {
              story: SAMPLE_TEXT,
              createSceneOnNewLine: true,
              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);

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

  ```python Python theme={null}
  def create_text_to_video():
      try:
          print("Creating video from text...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  'videoName': 'my_first_text_video',
                  'scenes': [
                      {
                          'story': SAMPLE_TEXT,
                          'createSceneOnNewLine': True,
                          '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}")

          return job_id

      except requests.exceptions.RequestException as error:
          print(f"Error creating video: {error}")
          raise
  ```
</CodeGroup>

### Step 3: Monitor Progress

Check the status of your video until it is ready:

<CodeGroup>
  ```javascript Node.js theme={null}
  async function waitForVideo(jobId) {
    console.log("\nMonitoring video creation...");

    while (true) {
      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") {
        console.log("\n✓ Video is ready!");
        console.log("Video URL:", statusResponse.data.data.videoURL);
        return statusResponse.data;
      } else if (status === "failed") {
        throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
      }

      // Wait 5 seconds before checking again
      await new Promise(resolve => setTimeout(resolve, 5000));
    }
  }

  // Run the complete workflow
  createTextToVideo()
    .then(jobId => waitForVideo(jobId))
    .then(result => console.log("\nDone!"))
    .catch(error => console.error("Error:", error));
  ```

  ```python Python theme={null}
  def wait_for_video(job_id):
      print("\nMonitoring video creation...")

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

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

          if status == 'completed':
              print("\n✓ Video is ready!")
              print(f"Video URL: {response.json()['data']['videoURL']}")
              return response.json()
          elif status == 'failed':
              raise Exception(f"Video creation failed: {response.json()}")

          # Wait 5 seconds before checking again
          time.sleep(5)

  # Run the complete workflow
  if __name__ == '__main__':
      job_id = create_text_to_video()
      result = wait_for_video(job_id)
      print("\nDone!")
  ```
</CodeGroup>

## Understanding the Parameters

### Required Parameters

| Parameter        | Type   | Description                                                  |
| ---------------- | ------ | ------------------------------------------------------------ |
| `videoName`      | string | A unique name for your video project (used for organization) |
| `scenes`         | array  | List of scenes to include in your video (minimum 1 scene)    |
| `scenes[].story` | string | The text content that will be converted to video             |

### Scene Control Options

| Parameter                    | Type    | Default | Description                                         |
| ---------------------------- | ------- | ------- | --------------------------------------------------- |
| `createSceneOnNewLine`       | boolean | false   | Creates a new scene at each line break in your text |
| `createSceneOnEndOfSentence` | boolean | false   | Creates a new scene at the end of each sentence     |

<Tip>
  **Scene Creation Best Practices:**

  * For short, punchy videos (like social media): Set both `createSceneOnNewLine` and `createSceneOnEndOfSentence` to `true`
  * For longer, narrative videos: Set both to `false` to keep related content together
  * For paragraph-based content: Set `createSceneOnNewLine` to `true` only
</Tip>

## How Scene Creation Works

The AI automatically determines scene breaks based on your settings:

### Both Options Enabled (Recommended for Social Media)

```javascript theme={null}
{
  createSceneOnNewLine: true,
  createSceneOnEndOfSentence: true
}
```

**Result:** Maximum scene breaks - new scene for each sentence AND paragraph
**Best for:** Short-form content, social media clips, dynamic videos

### Only Sentence Breaks

```javascript theme={null}
{
  createSceneOnNewLine: false,
  createSceneOnEndOfSentence: true
}
```

**Result:** New scene at each sentence, paragraphs stay together
**Best for:** Educational content, explainer videos

### Only Line Breaks

```javascript theme={null}
{
  createSceneOnNewLine: true,
  createSceneOnEndOfSentence: false
}
```

**Result:** New scene at each paragraph/line break
**Best for:** Article-to-video, blog content

### No Automatic Breaks

```javascript theme={null}
{
  createSceneOnNewLine: false,
  createSceneOnEndOfSentence: false
}
```

**Result:** All text stays in one scene
**Best for:** Short quotes, single-thought videos

## What Happens Behind the Scenes

When you submit your text, Pictory's AI:

1. **Analyzes Your Text** - Understands the context and key concepts
2. **Breaks Into Scenes** - Splits text based on your scene settings
3. **Selects Visuals** - Automatically chooses relevant stock images/videos for each scene
4. **Generates Captions** - Creates animated text overlays synchronized with the content
5. **Renders Video** - Compiles everything into a polished video file

<Note>
  **Processing Time:** Videos typically take 3-10 minutes to create, depending on length. The API processes asynchronously, so you receive a job ID immediately and can check status periodically.
</Note>

## Understanding the Response

### Initial Response (Job Created)

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "abc123def456",
    "status": "in-progress"
  }
}
```

### Completed Response

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "abc123def456",
    "status": "completed",
    "videoURL": "https://cdn.pictory.ai/videos/your-video.mp4",
    "duration": 45.5,
    "scenes": 5
  }
}
```

## Common Use Cases

### Marketing Content

```javascript theme={null}
const marketingText =
  "Introducing our new product! " +
  "50% faster than competitors. " +
  "Available now for $99.";
```

### Educational Videos

```javascript theme={null}
const lessonText =
  "Today we'll learn about photosynthesis. " +
  "Plants convert sunlight into energy. " +
  "This process produces oxygen for us to breathe.";
```

### Social Media Posts

```javascript theme={null}
const socialText =
  "5 tips for better productivity:\n" +
  "1. Start with your hardest task\n" +
  "2. Take regular breaks\n" +
  "3. Minimize distractions";
```

## Troubleshooting Common Issues

<AccordionGroup>
  <Accordion title="❌ Error: 'Invalid API Key'">
    **Problem:** Your API key is incorrect or expired.

    **Solution:**

    1. Check that your API key starts with `pictai_`
    2. Verify your subscription is active at [API Access page](https://app.pictory.ai/api-access)
    3. Make sure you are passing it in the `Authorization` header
  </Accordion>

  <Accordion title="⏱️ Video stuck at 'in-progress' for over 30 minutes">
    **Problem:** The job may have encountered an issue.

    **Solution:**

    1. Check the job status one more time
    2. Verify your text content is not excessively long (keep under 5,000 characters for best results)
    3. [Contact support](https://pictory.ai/contact) with your job ID if it has been over an hour
  </Accordion>

  <Accordion title="❌ Error: 'Story text is required'">
    **Problem:** The `story` field is empty or missing.

    **Solution:**
    Ensure each scene has a `story` field with actual text content:

    ```javascript theme={null}
    scenes: [{
      story: "Your text here",  // Must not be empty
      createSceneOnNewLine: true
    }]
    ```
  </Accordion>

  <Accordion title="Scenes Do Not Break Where Expected">
    **Problem:** Scene creation settings do not match your expectations.

    **Solution:**

    * Review the scene control options above
    * Test with both `createSceneOnNewLine` and `createSceneOnEndOfSentence` set to `true` for maximum control
    * Use manual line breaks (`\n`) in your text where you want scene breaks
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you know the basics, enhance your videos with these features:

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

  <Card title="Customize Captions" icon="closed-captioning" href="/guides/text-to-video/text-to-video-captions">
    Translate or customize subtitle text
  </Card>

  <Card title="AI-Generated Visuals" icon="wand-magic-sparkles" href="/guides/ai-generated-visuals/background-images">
    Use AI to generate unique visuals instead of stock
  </Card>

  <Card title="Apply Brand Settings" icon="palette" href="/guides/branding-customization/brand-settings">
    Add your logo, colors, and fonts automatically
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

<CardGroup cols={2}>
  <Card title="Render Storyboard Video" icon="video" href="/api-reference/videos/render-storyboard-video">
    Direct video rendering from text (used in this guide)
  </Card>

  <Card title="Create Storyboard Preview" icon="eye" href="/api-reference/videos/create-storyboard-preview">
    Create preview before rendering
  </Card>

  <Card title="Get Storyboard Preview Job" icon="clock" href="/api-reference/jobs/get-storyboard-preview-job-by-id">
    Monitor storyboard creation progress
  </Card>

  <Card title="Get Text Styles" icon="font" href="/api-reference/branding/get-text-styles">
    Customize subtitle appearance
  </Card>
</CardGroup>